Skip to main content

​
How to troubleshoot authentication

This guide walks through the most common authentication problems and how to resolve them.

​
Start with the doctor command

The quickest first step is:
This checks your installation, authentication status, and connectivity, and prints a summary of what is working and what is not. Fix the items it flags before going further.

​
Check your current auth status

This prints whether you are authenticated, the auth method (OAuth session or API key), and the account you are authenticated as. If it returns an error, you are not authenticated.

​
You are not authenticated at all

Run the login flow:
This opens a browser window for OAuth. Complete the login and return to the terminal. The CLI saves the session to ~/.landbase/platform.json. If you cannot open a browser (CI environment, remote server), use an API key instead:
Paste your API key when prompted.

​
Your session has expired

Platform OAuth sessions expire. If commands are returning auth errors after previously working, your session has expired. Re-run:
This refreshes the session. You do not need to log out first.

​
You have an API key but commands are failing with auth errors

Check that the key is correctly set:
If it says “no key found”, set it explicitly:
Or export it as an environment variable:
The environment variable takes precedence over the stored key.

​
Wrong mode: platform vs. legacy

There are two auth modes. Most users are on platform mode (the default). If you are getting auth errors that reference lbk_ keys when you have an lbs_ session (or vice versa), you may have the wrong mode active. Check which mode is active:
To force legacy mode (direct AgentOS, API key only):
To go back to platform mode, unset the variable:
See Platform mode vs. legacy mode for more background.

​
Clear stored credentials and start fresh

If you are unsure what state your credentials are in, clear everything and re-authenticate:
logout removes the stored session from ~/.landbase/platform.json and ~/.landbase/config.json. After this, auth status should say “not authenticated” and auth login will walk you through a fresh login.

​
Still failing after all of the above

Run with verbose output to see what is being sent and received:
The verbose output shows the exact HTTP request and response headers, which can reveal whether the issue is a credentials problem, a connectivity problem, or an API error. If you are still stuck, contact Landbase support with the verbose output (redact your API key before sharing).