Troubleshoot ThingsBoard CLI

This page lists common ThingsBoard CLI problems. Each problem shows the cause and the fix. To learn how the parts of the CLI work together, see How it works.

When tb config or tb init tests a connection and the test fails, the CLI shows Connection failed: and the reason. Then it asks if you want to try again. The browser page Connect ThingsBoard CLI shows the same reasons. Other commands show the error in a box with the title Error.

The API key is not valid. It can be wrong, expired, or disabled. Create a new key and try again.

Other commands show API error (401) for the same problem.

Cause: The key has an error, or it expired, or someone disabled it.

Fix: Create a new API key in ThingsBoard and enter it again. For details, see API keys. To change the key of a profile, run tb config edit <name>.

The user of this API key does not have the necessary permissions. Use a tenant administrator.

Other commands show API error (403) for the same problem.

Cause: The user who created the API key is not a Tenant Administrator.

Fix: Sign in to ThingsBoard as a Tenant Administrator. Create a new API key and enter it again.

The host '<host>' was not found. Check the URL. For Cloud EU, use https://eu.thingsboard.cloud.

Other commands show Could not reach <host>: DNS lookup failed.

Cause: The URL has an error, or your network cannot find the server.

Fix: Check the URL. For Cloud EU, use https://eu.thingsboard.cloud. To see the URL of the default profile, run tb config show.

<url> is not a ThingsBoard server. Check the URL.

Cause: The server answers, but it is not ThingsBoard, or the URL has a wrong path.

Fix: Enter only the base URL of ThingsBoard, like https://iot.example.com.

The CLI cannot connect to <url>. Check the URL and your network.

Other commands show Could not reach <host>: connection timed out. or Could not reach <host>: connection refused.

Cause: The server is down, the port is wrong, or a firewall stops the connection.

Fix: Open the URL in your browser. If the page does not open, check the server and the port. For your own server, add the port to the URL, like http://192.168.1.10:8080.

The TLS certificate of '<host>' was not accepted. Check the URL and the certificate of the server.

Other commands show Could not reach <host>: TLS/SSL error: and the details.

Cause: The server uses a self-signed certificate, an expired certificate, or a certificate for another host name.

Fix: Check that the URL has the host name that the certificate is for. Ask the server administrator to install a valid certificate from a public certificate authority.

The CLI does not support self-signed certificates or certificates from a private certificate authority.

Cause: The CLI cannot open a browser, like on a remote server or in some agent sessions.

Fix: The CLI shows this text and a link:

Open this page in your browser to connect ThingsBoard CLI:
  http://127.0.0.1:<port>/<token>

Copy the link and open it in a browser on the same computer.

The page closes 15 minutes after it opens. After that time, the CLI shows The page was not completed in 15 minutes. To try again, run this command:

tb config --browser

Cause: The terminal started before the installer added the CLI to your PATH.

Fix: Open a new terminal window and try again. If the problem continues, run this command, then open a new terminal window:

uv tool update-shell

Cause: The agent loads the ThingsBoard skills only when it starts in the project folder. An agent that started in another folder, or before tb init, does not have them.

Fix: Restart the agent in the project folder:

• Claude Code: Type /exit, then run claude --continue in the project folder.
• Antigravity: Close the agent, then run agy in the project folder.

No entities to push.

Cause: The push target has no entity files. If you run tb push without a solution name, outside a solution folder, the CLI pushes the entities in the project root. Usually there are none there.

Fix: Add the solution name:

tb push <name>

To see the solutions in the project, run tb solution list. If the solution is empty, ask the agent to build it, or save an entity with a command like tb device save --solution <name>.

Cause: Without a solution name, the CLI selects the solution from the current folder. In the project root, it uses the root entities.

Fix: Add --solution <name> to the command. The option works in all folders of the project. For tb push, tb validate, and tb emulator run, put the solution name after the command, like tb push <name>.

If the name is wrong, the CLI shows Unknown solution '<name>'. Available solutions: and the list of solutions.

Local changes would be overwritten:
  <file>

Then the CLI shows Commit/stash them or pass --force.

Cause: The files that tb pull must write have uncommitted git changes. The CLI stops, so that it does not delete your work.

Fix: Commit or stash your changes, then run tb pull again. To overwrite the changes, add --force.

Cause: tb push sends the files of your project. It replaces changes that someone made in the ThingsBoard UI to the same entities.

Fix: Before you push, run tb pull to write the UI changes to your files. Commit them, then push. To get back a lost change, make it again in the files, or use git to find an earlier version.

Cause: The push did not write the demo history, or the live demo data stopped.

Fix: Write the demo history:

tb push <name> --run-tasks

Then send live data:

tb emulator run <name> --duration 10m

If a device already has data for the emulated keys, tb push --run-tasks does not write the history again. The CLI shows Skipping DEVICE … (keys already populated: …). To replace that data, add --force-emulators. This option deletes the existing data of these keys first.

If tb emulator run shows Device '<name>' is not in ThingsBoard. Run 'tb push' first; skipped., push the solution, then run the emulator again.

Cause: Some time after a deployment, the agent asks Did you achieve the result you expected? It asks at most one time in four hours.

Fix: Select an answer, or select Skip. The feedback is anonymous. To stop the questions, turn off analytics with tb config analytics false. To send feedback at any time, run tb feedback.

Cause: An error message does not show enough detail, or you want to report a bug.

Fix: Add --debug to the command, or set TB_DEBUG=1. The CLI shows each HTTP request and response:

tb push <name> --debug

• Commands: the commands and their options.
• Configuration: profiles, API keys, and environment variables.