Troubleshooting

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:

uv add cpsl

or:

pip install cpsl

Then verify:

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:

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:

capsule secret create OPENAI_API_KEY=sk-...

Declare it on the app:

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:

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(...). Check that the page is registered before the module finishes importing:

@app.page("Overview", icon="layout-dashboard")
def overview():
    return cpsl.ui.Page([...])

For React pages, check the component path:

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.

@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:

capsule fs create reports

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

Then create subdirectories inside the runtime before writing:

os.makedirs("/data/reports", exist_ok=True)

Local and hosted behavior differ

Check SDK And Runtime Versions. Hosted runtimes can use the platform-pinned SDK version even if your local virtual environment has a different cpsl installed.

Start Here

Build Apps

Features

Concepts

Updates

Troubleshooting

`capsule` command not found

`capsule serve` says you are not authenticated

Secret missing in the runtime

Import error after deploy

Page does not show in the sidebar

Data handler returns empty integration state

Filesystem path is missing

Local and hosted behavior differ

​capsule command not found

​capsule serve says you are not authenticated

​Secret missing in the runtime

​Import error after deploy

​Page does not show in the sidebar

​Data handler returns empty integration state

​Filesystem path is missing

​Local and hosted behavior differ

​Related

`capsule` command not found

`capsule serve` says you are not authenticated

Secret missing in the runtime

Import error after deploy

Page does not show in the sidebar

Data handler returns empty integration state

Filesystem path is missing

Local and hosted behavior differ

Related