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

# Troubleshooting

> Common setup, serve, deploy, auth, secret, and runtime issues.

Start here when a Capsule command or app does not behave the way you expect.

## `capsule` command not found

Install `cpsl` in the active environment:

```bash theme={null}
uv add cpsl
```

or:

```bash theme={null}
pip install cpsl
```

Then verify:

```bash theme={null}
which capsule
capsule --help
```

If `which capsule` points at the wrong environment, activate the virtual environment you installed into.

## `capsule serve` says you are not authenticated

Run:

```bash theme={null}
capsule login
```

`capsule login` authenticates you as the builder. It is required for `serve`, `deploy`, and workspace resource commands.

## Secret missing in the runtime

Create the workspace secret:

```bash theme={null}
capsule secret create OPENAI_API_KEY=sk-...
```

Declare it on the app:

```python theme={null}
app = cpsl.App(
    name="my-app",
    image=cpsl.Image(),
    secrets=["OPENAI_API_KEY"],
)
```

For local-only testing, also export the environment variable before `capsule serve`.

## Import error after deploy

Make sure the dependency is in the runtime image:

```python theme={null}
app = cpsl.App(
    name="my-app",
    image=cpsl.Image(python_packages=["openai", "requests"]),
)
```

Installing a package locally is not enough. The Capsule runtime installs packages from `cpsl.Image(...)`.

## Page does not show in the sidebar

Check that the page is registered before the module finishes importing:

```python theme={null}
@app.page("Overview", icon="layout-dashboard")
def overview():
    return cpsl.ui.Page([...])
```

For React pages, check the component path:

```python theme={null}
app.add_page("Dashboard", component="pages/dashboard.tsx")
```

## Data handler returns empty integration state

If a page needs user credentials, gate it and read integrations from `RequestContext`.

```python theme={null}
@app.data("repos", access="authenticated")
async def repos(ctx: cpsl.RequestContext):
    github = ctx.integrations.get(cpsl.Integration.GITHUB)
    if not github:
        return {"connected": False, "repos": []}
```

The user still needs to connect the integration in the hosted app.

## Filesystem path is missing

Create the filesystem and mount it:

```bash theme={null}
capsule fs create reports
```

```python theme={null}
app = cpsl.App(
    name="reports",
    image=cpsl.Image(),
    filesystems={"/data": cpsl.FileSystem("reports")},
)
```

Then create subdirectories inside the runtime before writing:

```python theme={null}
os.makedirs("/data/reports", exist_ok=True)
```

## Local and hosted behavior differ

Check [SDK And Runtime Versions](/sdk-runtime-versions). Hosted runtimes can use the platform-pinned SDK version even if your local virtual environment has a different `cpsl` installed.

## Related

* [Installation](/installation)
* [Quickstart](/quickstart)
* [Deploy An App](/build/deploy-an-app)
* [CLI Reference](/reference/cli)