Troubleshooting Guide

Overview

This chapter organizes troubleshooting strategies around common symptoms. It applies to the following scenarios:

• The CLI command cannot be found, or it errors out immediately after launch.
• Login fails, the token has expired, or tool invocations return 401 / 403.
• Model calls fail, the API key is misconfigured, or requests trigger rate limits.
• Post-launch behavior does not match expectations (e.g. an abnormal model list, the wrong working directory, missing skills, etc.).

It is recommended to verify the following three baseline conditions first:

• The CLI command runs normally.
• The LLM service is reachable.
• The current login session is valid.

Once these baseline capabilities have been confirmed, proceed to investigate the specific symptom in more detail.

General Troubleshooting Workflow

When something goes wrong, it is recommended to check the following in order:

1. Check that the CLI is usable.

In your shell, run:

unitarylab --help

Confirm that the CLI launches normally and prints the expected list of subcommands.

2. Check the login state.

Run:

unitarylab whoami

Confirm that the current token is still within its validity period.

3. Check the LLM configuration.

Run:

unitarylab configure

Walk through the configuration flow again — the CLI will automatically perform a connectivity check.

You can also run the following inside an active session:

/config

4. Ask the Agent to self-diagnose.

Inside a session, simply describe what you are seeing, for example:

A moment ago I asked you to save a file, but the terminal printed nothing. Can you help me work out what might have gone wrong?

The Agent will attempt to self-diagnose and analyze the problem using the tools currently available to it.

5. Confirm whether any commands have changed.

Run:

/help

Confirm whether command names or argument formats have changed in the current version.

Command Not Found

Symptom

In your shell, you run:

unitarylab

and you get:

command not found

Possible Causes

• The CLI has not been installed correctly.
• The directory containing the executable is not on your PATH.
• The current shell and the installation environment do not match (for example, the CLI was installed inside a virtualenv, but you are running it from a different environment).

Diagnostic Steps

1. Confirm that the current shell, Python environment, and PATH configuration match your expectations.
2. Check that the CLI is in fact installed in the current environment.
3. Reach out via the internal release channel to confirm the recommended installation method for the current version.

The full installation procedure will be described in Quick Start.

CLI Automatically Enters configure on Launch

Symptom

After running unitarylab, instead of entering the conversation interface, you are prompted to fill in:

• Provider
• API Base
• API Key

Explanation

The CLI did not detect a complete LLM configuration. Common causes include:

• This is your first time running the CLI and the configuration file has not yet been initialized.
• The local configuration file has been deleted, overwritten, or corrupted.
• You used --dotenv <path>, but no valid configuration exists at the target path.

After configuration is complete, the CLI will automatically enter the conversation interface.

Login-Related Issues

”Please run unitarylab login first” message

Symptom

When you run:

unitarylab

or:

unitarylab start

the CLI exits immediately with a message indicating that you need to log in.

Possible Causes

• This is your first time using the CLI and you have not yet logged in.
• The token has expired (a token with less than 60 seconds of remaining validity is treated as expired).
• You recently ran:

unitarylab logout

Solution

Run:

unitarylab login

If you are in a non-terminal environment (for example, CI, a container, or a background process), the CLI will not automatically open the login flow. Please complete login from an interactive terminal first.

Tool Invocations Return 401 / 403

Symptom

When the Agent calls a remote tool, it returns an error similar to:

Status: 401, Response: {"code": ..., "message": "..."}

Explanation

This is the CLI’s expected behavior.

For 401 / 403 errors, the CLI does not automatically retry or silently refresh the login state. Instead, it passes the original error through to the model, so that the model can prompt the user to log in again.

Solution

Inside the session, run:

/login

Or exit the session and run:

unitarylab login

After logging in again, simply resend the previous request.

LLM Configuration Issues

Model Returns 401 / invalid API key

Symptom

Immediately after sending a request, the model returns an API-key-related error.

How to Handle

In a terminal environment, the CLI will automatically ask whether you want to reconfigure immediately.

If you confirm, the CLI enters the same flow as configure. Once configuration is complete, you can resend the previous request directly.

If the current environment does not support interactive input, return to your shell and run:

unitarylab configure

The Model List Contains Invalid Entries

Symptom

In the output of /model or /models list, you see:

• Deprecated models
• Invalid model IDs
• Placeholder example models
• Models that cannot be called successfully

For example:

your-model-id
example

Diagnostic Steps

1. View the current model list:

/models list

2. Remove the invalid models:

/models remove <id>

3. Re-fetch the model list from the provider:

/models refresh

The CLI automatically refuses to write obvious placeholder IDs. If such IDs are still present, it usually means they were added by manually editing the configuration file.

Default DashScope Models Still Appear After Switching to a Custom Provider

Symptom

After switching to a custom provider, the default example models from DashScope still appear in the model list.

Explanation

At launch, the CLI checks whether the provider and the source of the model list are consistent, and prints a warn message if they are not.

Solution

Either of the following two approaches is recommended:

1. Re-run:

/config

The CLI will re-fetch or reconfigure the model list based on the current provider.

2. Manually remove the unrelated models:

/models remove <id>

Working Directory and Session Issues

Shell Directory Does Not Change After /cd

Symptom

Inside a session you run:

/cd <path>

The Agent’s path changes, but the current directory of the host shell does not.

Explanation

This is the expected behavior.

The /cd command in the CLI only modifies the Agent’s logical working directory; it does not modify the host shell’s os.getcwd().

If you also need to change the shell’s current directory, run the following separately in your shell:

cd <path>

See: Session and Working Directory Guide

Restored Session Has an Unexpected Working Directory

Explanation

The CLI automatically restores the working directory that was last used in a given session.

If you frequently switch between multiple directories, the restored directory may not match what you expect right now.

Solution

After entering the session, first run:

/pwd

to confirm the current directory.

If needed, then run:

/cd <path>

to switch to the target directory.

Skill-Related Issues

/skills Is Empty or Missing Expected Skills

Symptom

After running:

/skills

you do not see the skills you expected.

Possible Causes

• The skill set in the current release differs from that of a previous version.
• The skill directory did not load successfully.

Solution

1. Inside the process, type:

/<skill-name>

and press Tab to inspect the autocomplete results — this confirms which skills are currently available.

2. Reach out via the internal release channel to confirm whether the target skill is included in the current release.

Agent Does Not Drill Down After Invoking a Skill

Symptom

After invoking an index skill, the Agent does not continue down the skill reference chain into a sub-skill.

Recommended Approach

Be as explicit as possible about the target skill, for example:

Please use the cryptography/shor skill to complete the following task

or invoke the specific skill directly:

/shor

to skip the index layer.

Contact Technical Support

If the steps above still do not resolve your issue, we recommend collecting the following information before submitting feedback:

• The output of unitarylab --help (to confirm the version and command set)

• The output of unitarylab whoami (please do not include sensitive information)

• The self-check information printed at session startup (version, environment, operating system, timing, etc.)

• A complete reproduction trace:

  • Which commands you ran
  • The output at each step
  • The final error message

Do not submit sensitive credentials such as API keys or passwords. If your logs contain sensitive information, please redact it before submitting.