Troubleshooting

kotao login hangs forever

The CLI is waiting on you to confirm in the browser. Look back at the terminal — there’s an 8-character code and a URL printed before the spinner started. Open the URL on any device (laptop, phone, tablet), sign in to Kotao, enter the code.

If the code expired (30-minute window), ctrl-c and re-run kotao login for a fresh one.

kotao whoami says “Not authenticated”

Either you never ran kotao login on this machine, or your refresh token has been revoked (server-side logout from another device, or it’s been more than 30 days since your last call). Run kotao login again.

kotao theme push says “Slug already taken”

Another theme in your workspace already uses this slug. Slugs are unique per workspace. Either pick a different slug (edit id in theme.json AND slug in kotao.theme.toml), or coordinate with the other theme’s owner.

If the existing theme is one you no longer want, ask an admin to delete it via the API — there’s no public delete flow for now.

kotao theme push says “Version 0.1.0 already exists”

You’re trying to push a version you’ve already pushed. Bump theme.json.version and try again. Versions are immutable once published; the only way to ship updates is a fresh version.

kotao theme push succeeds but the site doesn’t change

Two reasons:

1. The site isn’t configured to use your theme yet. PATCH the site with {"theme_id": "<your-slug>"} (see Publishing → After ready). Until 4D ships an editor UI, this is a manual API call.
2. The site has theme_version pinned to an older version. The site’s theme_version field (when set) overrides “use the latest ready version”. Either bump the site’s pin or unset it.

Build failed with section_coverage_incomplete

Your theme declares it renders sections that aren’t wired in src/theme.ts. The error message lists which types are missing. Either add renderers for them in src/sections/<type>/Section.astro and import them in src/theme.ts, or remove the types from theme.json.sections if you don’t want this theme to support them.

Build failed with manifest_invalid

theme.json doesn’t validate against the SDK contract. The most common cause is a typo in a field name (displayName vs display_name — it’s camelCase) or a missing required field (sdkVersion is required since SDK 0.1.0). Diff against a freshly-scaffolded theme.json to spot what’s off.

kotao theme dev shows the wrong content

theme dev renders the scaffold’s fixture data, not real workspace content. To preview against real content, push the theme and apply it to a staging site for now. The --with-workspace flag for live workspace data is on the roadmap.

kotao theme dev left the runtime checkout dirty

A hard kill (kill -9, OS reboot) bypasses the cleanup handler that restores active-theme.ts. Inside the runtime checkout:

git checkout src/active-theme.ts

Two kotao theme dev processes at once

The second one’s swapActiveTheme() will overwrite the first’s swap, and ctrl-c on either restores from whatever the LAST swap captured — which may not be the original linen import.

Run one theme dev at a time. If you need to flip between themes quickly, run them on different ports against separate runtime checkouts.

theme push is rejected with a 401 mid-flow

Your access token expired between two API calls. The CLI tried to refresh transparently but the refresh itself failed — probably because your refresh token was revoked elsewhere. Run kotao login again to get a fresh pair, then retry the push.

Tarball too large

kotao theme push enforces a 50 MB cap on the source tarball. If you hit it:

1. Run kotao theme push once more — the error message includes a breakdown of the largest files.
2. Move large binary assets (images, video, fonts) to Cloudflare Images / Stream / R2 and reference them by URL from your sections.
3. Add anything else to .kotaoignore (gitignore syntax).

Asking for help

• Check the build log: GET /sites/themes/versions/{vid}/logs returns a presigned URL valid for 1 hour.
• For everything else, contact support with the version_id from the failure.