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.
The background list in config.json names the files sdk.run may start. Each must be a path inside the expansion folder that exists. See Manifest.
The keys of requires are expansion ids (lowercase a-z, 0-9, _), and the values are version ranges, like sdkVersion.
type is optional. Leave it out, or use "app" for an app. See Manifest.

Requirement errors

These mark the expansion Crashed at start. See requires.
Install the expansion named, or remove it from requires.
The required expansion is installed but not ready. The message ends in disabled, needs-approval or error: enable it, approve its permissions, or fix its own error first.
The required expansion crashed while starting. Its own card and log say why.
Update the required expansion, or widen your range if you know the installed version works.
Two or more expansions require each other. Break the cycle: usually one of them only needs the other’s service at runtime, which services.whenAvailable handles without a requires entry.

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.
Your copy of Lode Studio cannot check keys for expansions that are not published yet, so it does not load yours as Untrusted. Update Lode Studio to the latest release. If the message stays, contact support.
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, sdk.storage.files for your own data, 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.
sdk.settings.app only reads theme, fontSize, editorFontSize, debug, sounds, autoSave and notifications. For your own settings, use sdk.settings.get.
Background scripts must be listed in config.json background. Add the file there and save.
The call needs a project and the window has none open, for example from a route or a home widget. Pass projectId explicitly.
A function the app called (an exporter, transform, importer, sync hook, interceptor, …) did not finish in time: 30 seconds for most stages, 10 minutes for exporters, importers, transforms, sync hooks and sync-script directives. The call is skipped and the export, sync or import continues. Move heavy work to a background script or do less per call.
A path passed to sdk.project, sdk.storage.files or an exporter’s output resolved outside the folder it belongs to, for example through ../. Use paths relative to that folder.
The app refused a contribution, for example a logic-editor catalog key that is already taken. Built-in keys can never be replaced; pick another key.
Ordinary JavaScript. The file and line in the card are yours; the log has the stack.

Packing errors

These come from compass in the app’s console.
The console lists the ids it does know underneath. compass list shows them too. The id is the one in meta.json, not the folder name.
Followed by the same manifest and import problems the Expansions page would show. Nothing is written until they are fixed; compass check my_expansion re-runs the check without writing.
An older package is in the way. Add --force, or move it first.

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. A keybinding does nothing. Bindings are ignored while focus is in a text field (inputs, textareas, Monaco) unless they have inInput: true. Also check when. An interceptor does not fire. item:delete, item:rename, item:duplicate and folder:delete interceptors see the user’s actions in the project browser, not changes made through sdk.project. 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.