It does not appear at all
Is there ameta.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
sdkVersion range excludes this app. Widen it, or update the app.
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.
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.requires.
disabled, needs-approval or error: enable it, approve its permissions, or fix its own error first.
services.whenAvailable handles without a requires entry.
Key errors
meta.json.
Import errors
sdk.project for project files, sdk.storage.files for your own data, or import the file into your expansion.
Runtime errors
sdk.settings.app only reads theme, fontSize, editorFontSize, debug, sounds, autoSave and notifications. For your own settings, use sdk.settings.get.
config.json background. Add the file there and save.
projectId explicitly.
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.
Packing errors
These come fromcompass in the app’s console.
compass list shows them too. The id is the one in meta.json, not the folder name.
compass check my_expansion re-runs the check without writing.
--force, or move it first.
Editor complaints
"Cannot find module 'sdk'" or "'./x.module.css'"
"Cannot find module 'sdk'" or "'./x.module.css'"
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
JSX errors about JSX.IntrinsicElements
JSX errors about JSX.IntrinsicElements
The React shim is missing. Same fix, or install
@types/react in the expansion folder.Changes not picked up
Changes not picked up
VS Code caches aggressively; run TypeScript: Restart TS Server.
Behaviour that surprises people
State disappears on reload. Module-level variables are re-run. UseuseProjectState / 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.