papermap command starts but login, workspace loading, streaming, or shell mode does not behave as expected.
Quick checks
Run these first:whoami says you are not signed in, run:
Common issues
Browser did not open during login
Browser did not open during login
The CLI prints the login URL after attempting to open your browser. Copy the printed URL into your browser manually.If you are on SSH or a headless machine, use the password fallback instead.
Login timed out
Login timed out
Browser login waits for a localhost callback for a limited time. Restart login and complete the browser flow promptly.Also check that your browser can reach the printed
http://127.0.0.1:<port>/callback URL after Papermap redirects.Custom frontend URL is rejected
Custom frontend URL is rejected
Browser login only allows production Papermap frontend hosts by default. Internal or development frontends require an explicit opt-in.Only use this with frontends you control.
Session expired
Session expired
The TUI attempts token refresh before forcing a new sign-in. If refresh fails, sign in again.If the issue repeats, log out and start with clean local auth state.
No workspaces appear
No workspaces appear
Confirm your account has access to workspaces.If the CLI returns no rows, create a database-backed workspace or use the web app to configure sources that require browser-based setup.
Workspace picker looks stale
Workspace picker looks stale
Refresh the local workspace cache, then relaunch the TUI.Logout also clears the workspace cache.
Workspace creation returns before connection is verified
Workspace creation returns before connection is verified
This is expected.
papermap workspace create creates the workspace row first, then Papermap verifies the database connection in the background.If the workspace later cannot answer questions, verify the host, port, database name, username, password, network access, and database permissions.Shell mode did not start
Shell mode did not start
! starts shell mode only from an empty prompt. If your prompt already has text, ! is typed into the prompt instead.Clear the prompt with Ctrl+L, then press ! again.Shell command is stuck or running too long
Shell command is stuck or running too long
Press
Esc to cancel the running shell command. Shell mode uses one-shot commands; there is no persistent shell session inside the TUI.Windows says pwsh.exe was not found
Windows says pwsh.exe was not found
The default Windows shell is PowerShell 7 (Save the file at
pwsh). Install PowerShell 7 or switch shell mode to Command Prompt.C:\Users\<name>\.papermap\config.yaml, then restart papermap.Credential store fails in CI or a container
Credential store fails in CI or a container
Force file-backed credential storage when the OS keyring is unavailable.Keep
~/.papermap/credentials private and out of source control.The terminal is too small
The terminal is too small
Papermap needs enough room to render the landing panel, chat layout, overlays, and key hints. Resize the terminal to at least roughly
60x20, then relaunch or continue.Slash does not open the command palette
Slash does not open the command palette
/ opens the command palette only when the prompt is empty and the TUI is not streaming. Clear the prompt with Ctrl+L, then press /.Reset local state
Use logout when you want to clear credentials and workspace cache.Still need help?
Contact Support
Send the command you ran, the error output, your operating system, and whether you used browser or password login.
Book a Demo
Get guided help setting up Papermap for your team.