> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lodemc.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Error messages and what they mean

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](/migration). 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

```
meta.json: "id" must be lowercase a-z, 0-9 and _, got "My-Exp"
```

Every problem is listed at once. Fix them together and save; no restart needed.

```
Built for SDK ^3.0.0, but this app provides SDK 2.0.0.
```

Your `sdkVersion` range excludes this app. Widen it, or update the app.

## Key errors

```
Expansion has invalid or missing key.
```

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`.

```
This API key belongs to a different expansion.
```

The key is valid, but bound to another id. Use the id it was issued for, or create a secret for this one.

```
Expansion is not published on NMCrate, and unpublished expansions need SECRETS_API_KEY in the app's .env to be checked.
```

Whoever builds the app needs to set `SECRETS_API_KEY`. See [Publishing](/publishing).

```
Failed to verify expansion: Network error
```

The app is offline, or NMCrate is unreachable. Nothing loads until it can check.

## Import errors

```
src/index.ts:2: "fs" is a Node built-in. Expansions have no Node access; use the sdk module instead.
```

There is no filesystem. Use [`sdk.project`](/sdk-reference#project) for project files, or import the file into your expansion.

```
src/index.ts:3: "lodash" is not one of this expansion's libraries. Available: greeter. Packages from npm cannot be imported.
```

npm packages cannot be bundled. Either write it yourself or put it in a [library](/libraries).

```
Cannot find "./pages/Counter". Tried: src/pages/Counter.ts, src/pages/Counter.tsx, ...
```

A typo or the wrong case. The list shows exactly what was tried.

```
import() needs a literal path so the expansion can be resolved ahead of time
```

Everything is resolved before your code runs, so a computed path cannot work. Import the candidates and pick between them.

## Runtime errors

```
<page> crashed at src/pages/Home.tsx:12
```

The component threw. The rest of the app is unaffected; fix and save, and Retry or reload.

```
project.writeFile blocked: needs "project:write" (not in meta.json)
```

Declare the permission and have it approved. See [Permissions](/permissions).

```
Cannot read properties of undefined (reading 'x')
```

Ordinary JavaScript. The file and line in the card are yours; the log has the stack.

## Editor complaints

<AccordionGroup>
  <Accordion title={`"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:

    ```json tsconfig.json theme={null}
    {
      "extends": "./.ldstudio/tsconfig.libs.json",
      "include": ["src", ".ldstudio/sdk.d.ts", ".ldstudio/react.d.ts"]
    }
    ```
  </Accordion>

  <Accordion title="JSX errors about JSX.IntrinsicElements">
    The React shim is missing. Same fix, or install `@types/react` in the expansion folder.
  </Accordion>

  <Accordion title="Changes not picked up">
    VS Code caches aggressively; run *TypeScript: Restart TS Server*.
  </Accordion>
</AccordionGroup>

## 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.