Skip to main content
Every message below appears on the Expansions page card, in the expansion’s log, or as an error card where a component should be.

​
It does not appear at all

Is there a meta.json? A folder with only main.js is treated as a legacy expansion. A folder with neither is ignored. Is the app looking where you think? Expansions live in Documents/LodeMC/LDStudio/Expansions/ (~/.local/share/... on Linux). A folder copied while the app is running is picked up within a second or two.

​
Manifest errors

Every problem is listed at once. Fix them together and save; no restart needed.
Your sdkVersion range excludes this app. Widen it, or update the app.

​
Key errors

NMCrate refused the key. Either it is unknown, it is disabled, or it belongs to a different expansion id than the one in meta.json.
The key is valid, but bound to another id. Use the id it was issued for, or create a secret for this one.
Whoever builds the app needs to set SECRETS_API_KEY. See Publishing.
The app is offline, or NMCrate is unreachable. Nothing loads until it can check.

​
Import errors

There is no filesystem. Use sdk.project for project files, or import the file into your expansion.
npm packages cannot be bundled. Either write it yourself or put it in a library.
A typo or the wrong case. The list shows exactly what was tried.
Everything is resolved before your code runs, so a computed path cannot work. Import the candidates and pick between them.

​
Runtime errors

The component threw. The rest of the app is unaffected; fix and save, and Retry or reload.
Declare the permission and have it approved. See Permissions.
Ordinary JavaScript. The file and line in the card are yours; the log has the stack.

​
Editor complaints

The .ldstudio folder is missing or your tsconfig.json does not include it. Load the expansion once in the app to regenerate it. If you wrote your own tsconfig.json, it must name the files explicitly, because TypeScript’s include globs skip dot-folders:
tsconfig.json
The React shim is missing. Same fix, or install @types/react in the expansion folder.
VS Code caches aggressively; run TypeScript: Restart TS Server.

​
Behaviour that surprises people

State disappears on reload. Module-level variables are re-run. Use useProjectState / useGlobalState, or write to the project. Two intervals running. Not possible with setInterval inside the expansion: timers are cleared on unload. If you see it, something escaped the SDK. Styles leak into the app. Imported CSS is scoped; sdk.theme.addStyle is deliberately not. Use the import for your own UI. An event fires twice. You registered the listener from a module that re-runs on reload and kept an old one alive outside the SDK. Let sdk.events.on own it.

​
Getting more detail

The Expansions page has a logs button per expansion with everything your expansion printed, plus its errors. sdk.log.debug lines are there too.