Troubleshooting
Where JSLab keeps your data and logs, how to copy a debug log, when Safe Mode starts, and fixes for common problems.
The first launch takes a few seconds
The first launch unpacks the app, which can take a few seconds. See Install JSLab.
Where your data lives
Everything JSLab stores lives in one folder:
~/Library/Application Support/dev.jslab.app/<channel>/<channel> is the build’s channel, such as canary or stable. Open Data Folder always goes to the right one. To open it, choose Open Data Folder in Settings → Advanced, or run Open Data Folder from the command palette.
| File or folder | What it holds |
|---|---|
settings.json |
Everything in Settings |
session.json |
Open tabs, their layout and the window’s state |
keybindings.json |
Your keyboard shortcut changes |
env.json |
Your environment variables, readable only by your account |
snippets.json |
Your snippet library |
license.json |
Your activated license |
ai/conversations/ |
Each tab’s AI Chat conversation, one <tab id>.json per tab |
tips.json |
Which first-week tips you’ve seen |
learn.json |
Which Learning & Tips entries you’ve opened |
update-ready.json, update-attempt.json, update-failed.json |
The state of an update in progress; delete update-failed.json to retry a failed version |
themes/ |
Themes you’ve imported |
packages/ |
The shared npm project every tab’s imports resolve against |
logs/main.log |
The application log |
jslab.sock |
The socket the jslab CLI talks to |
API keys aren’t in this folder: they’re in your macOS Keychain.
Logs and the debug log
- Help → Open Logs Folder opens the
logs/folder. The live log ismain.log. It’s capped at 5 MB and rotated, keeping 5 files in all. - Help → Copy Debug Log copies a redacted summary of recent activity to your clipboard. It’s the quickest way to share what happened without sharing your secrets. JSLab’s log never records a full license key or email.
When something goes wrong, JSLab’s notices point you to Copy Debug Log too.
Safe Mode
Safe Mode, the debug log and the logs folder help when something goes wrong.
JSLab starts in Safe Mode, with Auto Run paused for that session, in three cases. Each shows its own banner:
- JSLab didn’t shut down cleanly the last time it was running code.
- You held Shift while launching it.
- You chose Help → Restart in Safe Mode, or Restart in Safe Mode in Settings → Advanced.
Safe Mode doesn’t stop you running code by hand: ⌘R still works. It only stops Auto Run from firing on its own, so you can fix a tab that hangs or crashes before it runs again.
A run won’t stop
⇧⌘R stops a run, and kills it after 500 ms if it doesn’t respond. ⌥⌘R kills it immediately. If a run stops responding entirely, JSLab shows This tab isn’t responding on its own, with Kill and Wait. See The editor and live output.
A license key won’t activate
- Use the email you bought JSLab with. The key only works with the address it was issued to.
- Paste the whole key. Pasting the whole line from the email, “License key:” label and all, works too.
- License verification needs macOS 14 or later. On an older macOS, the License sheet says “Activating a license needs macOS 14 or later.” and Activate stays off.
- For a deactivated key, write to [email protected].
Settings or tabs didn’t come back
If settings.json or session.json can’t be read, JSLab restores it from its backup when it can, and tells you. If there’s no usable backup, it starts fresh and says so. A tab whose contents can’t be read opens empty and read-only, so JSLab never saves over the file on disk.
Something else
Write to [email protected], and include the debug log from Help → Copy Debug Log.