Skip to main content
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.