Skip to content

troubleshooting.mdx

Latest commit

 

History

History
135 lines (93 loc) · 2.77 KB

troubleshooting.mdx

File metadata and controls

135 lines (93 loc) · 2.77 KB
title Troubleshooting
description 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:

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(...).

Page does not show in the sidebar

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.

Related