Troubleshooting

Every error says what went wrong and, usually, what to do (hint). The common ones:

Message	What to do
not signed in (exit code 2)	kol login, then approve the code in the app: Companions → Creator portal
the code expired (or was already used)	Codes last 5 minutes. Run kol login again
could not reach the Kol host at …	Check your connection. During the preview, check KOL_HOST (echo $KOL_HOST)
no AI key	try and test run on your AI key. Add one in the app: Companions → Your AI key
your AI key was rejected	The key was revoked or has no credit. Add a new one in the app
too many try-outs this hour	120 an hour. Wait, or test less often (use kol prompt, it's free)
too many sign-in codes	Wait a few minutes before kol login again
persona.md still has template text	Delete every TODO: line in persona.md
no kol.json in …	Run the command inside your project, or pass --dir
this AI is published: pushing changes it for everyone right away	On purpose? kol publish (or kol push --live). See Publishing
kind can't change after the first push	Put kind back, or delete .kol/project.json to push it as a new AI
creation … is not on … or not yours	.kol/project.json points at an AI that's gone or belongs to another account. Delete .kol/project.json and push again
knowledge is over 40000 characters	Trim your knowledge files, or link fewer web pages
… : not a public web address (on push)	Pages in urls.txt must be public http(s) pages; local and private addresses are refused
kol: command not found	npm install -g kol-cli, or check that npm's global folder is on your PATH (npm prefix -g)

It answers badly

• Run kol prompt and read what it's told. Is the fact really in knowledge/? Is the persona clear about what to do?
• Too long? Say "one or two short sentences" in the persona, and add a maxWords check.
• Makes things up? Add "If it isn't in your notes, say you don't know" and a test that asks something not in the notes.
• Sounds wrong in a call but fine in text? Push, and try another voice.

The MCP server doesn't show up

• Run kol mcp in a terminal: it should wait silently (it talks on stdin/stdout). Press Ctrl-C.
• Check that kol is on the PATH your agent uses. If not, put the full path in .mcp.json (which kol).
• In Claude Code, /mcp lists servers and their status.

Still stuck?

Open an issue with the command, its --json output (remove anything private) and kol --version.