Troubleshooting

Kosh writes errors to stderr with a [✗] glyph and the active profile as a prefix:

(work) [✗] incorrect master password

Messages are lowercase, unpunctuated and article-free, because the UI supplies its own prefix. They read subject-first: failed to save credential, not could not save the credential.

---

Output glyphs

Glyph	Colour	Meaning	Stream
[✓]	green	Information / success	stdout
[✗]	red	Error	stderr
[!]	yellow	Warning	stderr
[?]	cyan	Prompt for input	stdout
[•]	grey	Muted / secondary detail	stderr

The (profile) prefix in grey precedes each of these, so you always know which vault produced the message.

---

Error messages

Vault and storage

Message	Cause	Fix
vault is not initialized	The active profile has no vault yet	Run kosh init
target profile vault is not initialized	kosh copy target exists but was never initialized	Switch to it and run kosh init, or recreate it with kosh profile create
failed to initialize vault	Vault row could not be written	Check disk space and that ~/.kosh is writable
failed to initialize vault storage	The SQLite file could not be opened or migrated	Check permissions on ~/.kosh/profiles/; the file may be corrupt
failed to fetch vault info	The vault row could not be read	The vault file may be corrupt — restore from a backup

Master password and secrets

Message	Cause	Fix
incorrect master password	The password did not decrypt the vault	Retry. Remember each profile has its own password — check kosh profile list
passwords do not match	The two master-password entries differed	Re-enter both carefully
secrets do not match	The two secret entries differed	Re-enter both carefully

There is no password recovery

If the master password for a profile is genuinely lost, that vault’s credentials are permanently inaccessible. Kosh stores nothing that could be used to reset it — this is by design.

Credentials

Message	Cause	Fix
credential not found	A lookup by ID, or by exact label and user, hit nothing	Check kosh list for the correct ID or exact spelling
no matching credential found	A search or filter came back empty	Try a shorter query, or kosh list to see what’s there
credential already exists	A rename would collide with an existing (label, user) pair	Pick a different label or user, or update the existing entry
credential label cannot be a command name	The label collides with a subcommand	Run kosh help for the reserved names and pick another label
failed to fetch credential	The credential row could not be read	Enable debug logging for the underlying error
failed to save credential	The credential could not be written	Check disk space and permissions
failed to delete credential	The delete did not complete	Check permissions; enable debug logging
failed to decrypt credential	The ciphertext could not be opened	The vault file may be corrupt or partially restored

Profiles

Message	Cause	Fix
profile does not exist	kosh use, kosh profile delete or kosh copy named an unknown profile	Check kosh profile list. Only profile create cleans up names, so the name you typed at creation may not be the stored one
profile already exists	kosh profile create name is taken	Pick another name, or kosh use the existing one. The check ignores case, so Work is taken by an existing work
invalid profile name	The name cleans up to nothing — e.g. "" or $__##	Use a name with at least one letter or digit — see Naming profiles
profile name is reserved by the operating system	The cleaned name is con, prn, aux, nul, com1–com9 or lpt1–lpt9	Pick another name. These are refused on every platform, not just Windows, to keep ~/.kosh/profiles portable
cannot delete active profile	You tried to delete the profile you are in	kosh use <other> first, then delete. The guard ignores case — WORK is the active profile when work is
cannot copy credential to active profile	kosh copy target is the current profile	Pick a different target. This guard ignores case too
failed to initialize vault	kosh profile create could not build the new vault	The half-made profile file is removed automatically and your active profile is unchanged — retry the same name
profile "<name>" was created but could not be activated	The vault was built successfully, but the config could not be written	The profile and its vault are intact. Run kosh use <name> to switch to it — do not recreate it
failed to fetch profile	The profiles directory could not be read	Check that ~/.kosh/profiles/ exists and is readable

Input and flow control

Message	Cause
invalid arguments	Wrong number or shape of arguments — check kosh <cmd> --help
id must be an integer	update, delete or copy was given a non-numeric ID
failed to read input	stdin could not be read — usually a non-interactive shell
operation aborted	You declined a confirmation, or cancelled an interactive picker. Not an error
search cancelled	The interactive search was dismissed with esc

---

Common situations

“Nothing happens when I run kosh”

kosh with no arguments opens the interactive search picker. If your vault is empty there is nothing to pick from — add something with kosh add first.

“The profile I just created doesn’t exist”

kosh profile create cleans up the name you give it and does not tell you it changed it:

kosh profile create "My Work!"   # actually creates My_Work
kosh use "My Work!"              # profile does not exist

Run kosh profile list to see the real name, and use that from then on. Only create cleans up names — use, profile delete and copy all match against what is on disk. See Naming profiles.

“There’s a profile I never finished creating”

Pressing Ctrl+C at the kosh profile create password prompt creates nothing, so this should not happen. The one narrow exception is an interrupt after the password is confirmed but before the vault finishes writing, which can leave an orphaned profile file behind.

It will not be your active profile and it has no vault, so it can be removed without a master password:

kosh profile delete <name>

“It asks for a password I’m sure is right”

Check which profile you are in. The prefix on every line tells you:

(work) [?] enter master password:

Each profile has an independent master password. kosh profile list shows which one is active.

“The clipboard copy fails on Linux”

Clipboard access needs a running display server (X11 or Wayland). On a bare TTY, or an SSH session with no display forwarded, there is no clipboard to write to.

wl-clipboard is no longer required

Kosh used to shell out to wl-copy on Wayland. As of v0.3.0 all platforms use a single cross-platform implementation, so installing wl-clipboard makes no difference.

“My terminal stopped echoing after Ctrl+C”

This was a bug in v0.2.3 and earlier. As of v0.3.0, interrupting a password prompt restores the terminal state and exits with code 130. If you are stuck in an old session, run stty sane (or reset).

“A command exited non-zero but I can’t tell why”

Kosh uses a single failure exit code (1) for every error class. To distinguish failures in a script, match on the stderr message. Turn on debug logging for the underlying cause.

---

Debug logging

Set the KOSH_DEBUG environment variable to any truthy value:

KOSH_DEBUG=1 kosh list          # bash / zsh

$env:KOSH_DEBUG=1; kosh list    # PowerShell

Accepted truthy values are anything Go’s strconv.ParseBool reads as true — 1, t, T, true, TRUE, True.

Output is structured (log/slog text handler), goes to stderr, and includes file:line source locations:

time=2026-08-05T09:11:47.221+05:30 level=DEBUG source=/…/cmd/list.go:60 msg="search complete" elapsed=412.5µs results=3

Debug logs cannot leak secrets

Credential, CredentialData and CredentialSummary implement slog.LogValuer and redact their sensitive fields as [REDACTED]. Ciphertext, nonces and ephemeral keys never appear in a log record, by construction rather than by discipline.

Redirect stderr to capture a log while keeping the interactive prompts usable:

KOSH_DEBUG=1 kosh search github 2> kosh-debug.log

The ldflag is gone

Debug output used to require rebuilding with -X …/internal/logger.BuildMode=debug. That mechanism was removed in v0.3.0 — released binaries can now be debugged directly. See Upgrading to v0.3.0.

---

Message changes in v0.3.0

If you script around Kosh’s output, these strings were renamed. The (profile) prefix is also new on every line.

v0.2.3	v0.3.0
vault not initialized	vault is not initialized
unable to fetch credential/s	failed to fetch credential
unable to save credential	failed to save credential
unable to read input	failed to read input
password does not match	passwords do not match
credential secret does not match	secrets do not match
no credential found	credential not found
credential match not found	no matching credential found
credential label cannot be same as command	credential label cannot be a command name
saved credential in the vault successfully	credential saved successfully
permanently deleted credential successfully	credential deleted successfully
copied credential to clipboard	credential copied to clipboard
list credentials with `list` command	run `kosh list` to list the stored credentials

Successful actions now consistently end in successfully:

vault initialized successfully
credential saved successfully
credential updated successfully
credential deleted successfully
credential copied successfully
profile created successfully
profile deleted successfully
profile switched successfully

---

Reporting a bug

Open an issue at git.plutolab.org/plutolab/kosh with:

• kosh --version
• your OS and terminal
• the exact command you ran
• the output of that command with KOSH_DEBUG=1 set

Debug output is safe to paste — secrets are redacted.