Common errors and known issues | Viam Documentation

Common errors and known issues

This document lists common errors encountered when working with Viam, and provides steps to resolve them. While many common issues and their possible resolutions are presented here, this list is not comprehensive.

To view logs or get a remote shell on a machine see Troubleshooting.

If you have encountered an error that is not listed here, we’d love to hear from you on our Community Discord! Please post the error message you received along with how you were able to trigger it and we’ll see if we can help.

Jump to an error by category:

Common installation errors

The authenticity of host ‘hostname.local’ can’t be established

Description: When following our installation guides, you will likely encounter this message the first time you try to make an ssh connection to your newly-imaged board. This is expected: ssh is advising you that it has not yet connected to this address, and prompts you for how to proceed.

Solution: The message will ask Are you sure you want to continue connecting?. Type yes and then press the return key to continue with the connection. You should receive a successful confirmation message similar to: Warning: Permanently added 'hostname.local' to the list of known hosts. This is only required for the first ssh connection you make to a newly-imaged board.

ssh: connect to host hostname.local port 22: Host is down

Description: Your computer is not able to connect to the board through ssh.

Solution: Ensure that both your computer and the board itself are connected to the internet, and verify each of the following:

If you are on a Windows computer, be sure that you do not have an outgoing firewall rule preventing ssh connections over port 22.
Your ssh connection string should resemble the following: ssh username@hostname.local. Be sure that you match hostname, username, and password exactly to what you initially configured when imaging your board.
If you are still unable to connect, restart your board and try your ssh connection again after a few minutes.
If that fails, try re-imaging your board following the installation guide appropriate for your board.
- If using the Raspberry Pi installation guide, be sure to carefully enter the configuration details under the Advanced Options (gear icon) button on the Raspberry Pi imager before you re-image your board.
- If you re-imaged your board and provided a different hostname, you may need to accept the ssh host key again by typing yes when prompted.
- If you re-imaged your board and provided the same hostname, you may see an error message similar to WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!.
  - If so, edit your ~/.ssh/known_hosts file to delete any single lines that begin with the board hostname you specified (like hostname.local or similar).
  - Afterwards, when you go to ssh to your board again, you will need to accept the ssh host key once more by typing yes when prompted.

ssh: connect to host hostname port 22: Connection timed out

Description: Your computer is not able to connect to the board through ssh before reaching a timeout.

Solution: Depending on your local network and board, it may take a minute or two for your ssh connection to successfully reach the board.

If you have just powered on or restarted your board, wait a few minutes and then try your connection again. Depending on your board, it may take a few minutes for the ssh service to be ready to receive connections.
If you encounter this error once or twice, try your ssh command again and wait until it completes.
If the error persists, try the solutions presented for the Host is down error message above.

Something went wrong trying to read the squashfs image

Full Error: Something went wrong trying to read the squashfs image. Open dir error: No such file or directory

Description: The viam-server installation or update process may have been interrupted partway, with some files either partially-written or missing.

Solution: Reinstall viam-server following the installation instructions.

AppImages require FUSE to run

Related Error: dlopen(): error loading libfuse.so.2

Description: viam-server is distributed for Linux as an AppImage, which requires FUSE (Filesystem-in-Userspace) version 2. FUSE version 2 is included in almost all modern Linux distributions by default, but some older Linux distros or minimal installs might not provide it out of the box, and some newer systems may ship with FUSE version 3 installed by default, which is not compatible with viam-server.

In addition, if you are installing viam-server within a Docker container, you may also experience this error due to its default security restrictions. FUSE is not required for macOS installations of viam-server.

Important

viam-server requires FUSE version 2 (libfuse2), not FUSE version 3 (fuse3 or libfuse3) or versions of FUSE previous to FUSE version 2 (fuse). To support a viam-server installation, you must install libfuse2.

Solution: If you receive this error, install FUSE version 2 on your Linux system according to one of the following steps:

If installing viam-server on a Raspberry Pi running Raspberry Pi OS (Debian GNU/Linux 12 bookworm or later), install FUSE version 2 with the following command:

    sudo apt install libfuse2
    ```

- If installing `viam-server` on Ubuntu, install FUSE version 2 with the following command:

```sh
    sudo add-apt-repository universe
    sudo apt install libfuse2
    ```

- If installing `viam-server` on a different Linux distribution, see the [AppImage FUSE troubleshooting article](https://github.com/AppImage/AppImageKit/wiki/FUSE) for more information.

- If installing `viam-server` on a Docker image, see [I get some errors related to something called “FUSE” - AppImage documentation](https://docs.appimage.org/user-guide/troubleshooting/fuse.html) for Docker-specific troubleshooting steps.

### PulseAudio: Unable to connect: Connection refused

**Additional Error:** `jack server is not running or cannot be started`

**Description**: When configuring a Linux board, Linux installations with broken or misconfigured sound libraries may experience one or both of these errors, even if not using audio components in the machine configuration.

**Solution:** Consult the documentation for your Linux OS and chosen sound library for guidance on installing any missing software dependencies. For example, if you are using `jackd` and `PulseAudio` on a Raspberry Pi, you can run the following to install any missing dependencies:

```sh
sudo apt install jackd qjackctl libpulse-dev pulseaudio

This error can be safely ignored if you do not intend to use audio on your machine.

Common connection errors

Failed to connect; retrying

Description: Viam is unable to communicate with your machine, and will attempt to reconnect every few seconds until it is able to do so. When a machine is disconnected, it will continue to run with its locally-cached current configuration, but will not be accessible for remote control or configuration through the web UI.

Solution: Check the following to ensure your machine is accessible to Viam:

Is the board connected to the internet?
Is viam-server running on the machine?
Are there errors in the machine’s logs?

To check whether viam-server is running and to read its logs, follow the steps in Machine shows as offline.

Error: error connecting to peer, error not connected

Full Error: error connecting to peer error not connected

Description: This error indicates a networking or connection issue.

Solution:

Verify your machine’s internet connection is stable and working properly.
Ensure your machine is using the correct machine cloud credentials. You can obtain your machine cloud credentials from the machine’s status in the part status dropdown to the right of your machine’s name on the top of the page.
If you are using API keys to connect, ensure you are using the correct credentials for the machine.
If you have multiple tabs open with your machine’s page, close all but one. Having too many connections can cause instability on some machines.

Error: cannot parse config: JSON: cannot unmarshal string into Go struct

Full Error: Error: cannot parse config: JSON: cannot unmarshal string into Go struct field Component.components.frame of type float64.

Description: A frame attribute may be malformed, and is preventing the parsing of the component’s configuration.

Solution: Check the CONFIGURE tab for your machine and look for a frame attribute, either in Frame or JSON mode. If you see a frame attribute that you didn’t create yourself, delete the whole frame object from the JSON config. In JSON mode, it will resemble the following:

"frame": {
   "orientation": {
      "value": {}
   },
   "parent": "",
   "translation": {
      "x": "",
      "y": "",
      "z": ""
   }
}

Error: resource build error: unknown resource type

Full Error:

Generalized example::

resource build error: unknown resource type: API "<API-TRIPLET>" with model "<MODEL-TRIPLET>" not registered

Camera example:

resource build error: unknown resource type: API "rdk:component:camera" with model "viam:orbbec:astra2" not registered.

Description: This error occurs when your configuration requests a model with an associated API and the combination of model name and API triplet is not registered with viam-server.

Solution:

If you are using a registry-provided models, ensure that your machine’s configuration includes the module that provides the model. On your machine page, find the module and navigate to it’s module page in the registry. You can find the correct model triplet (for example viam:camera:csi-pi) in the Components & services section of the registry page.
Check for typos in the model triplet. It must exactly match the model registered with viam-server.
Ensure the model supports the requested API. You can find the requested APIs next to each model entry in the Components & services section of the registry page.
Check for typos in the API triplet (for example rdk:component:camera).
Check the logs for other errors. It may be that the instantiation of the model is failing, for other reasons such as the hardware being disconnected.

Failed to connect to robot within time limit

Full Error: failed to connect to machine within time limit. check network connection, whether the viam-server is running, and try again. see https://docs.viam.com/dev/tools/common-errors/#conn-time-out for troubleshooting steps

Description: This error occurs when the host fails to connect to the robot within the time limit.

Solution: See Network Troubleshooting section.

Could not connect to machine part (context deadline exceeded)

Full Error: Error: Could not connect to machine part: context deadline exceeded; context deadline exceeded; mDNS query failed to find a candidate

Description: This error can occur connecting to a machine with the shell service indicating network issues.

Solution: See Network Troubleshooting section.

Could not connect to machine part (ResourceExhausted)

Full Error: Could not connect to machine part: error updating resources: rpc error: code = ResourceExhausted desc = exceeded request limit 100 on resource viam.robot.v1.RobotService

Description: This error occurs when there are more than 100 concurrent requests to a resource. These connections can come from modules or other scripts and apps.

Solution: Try to find bottlenecks in scripts or modules that are hitting APIs for the machine in loops. You can check operations and sessions for a machine on its CONTROL tab at the bottom of the screen. To adjust the per-resource limit for modules, you can set the VIAM_RESOURCE_REQUESTS_LIMIT environment variable on your machine to a positive integer higher than the default, 100.

Error while dialing app

Full Error: error while dialing app. Could not establish global, unified connection

Description: This error occurs when a machine cannot establish a connection to Viam within the timeout window, by default 15 seconds.

Solution: To adjust the initial app connection timeout, you can set the VIAM_CONFIG_READ_TIMEOUT environment variable on your machine to a positive integer higher than the default, 15.

exceeded request limit on resource

Full Error:

Error: exceeded request limit <LIMIT> on resource <RESOURCE>

Description:

This error occurs when there are more than, by default, 100 concurrent requests to a resource on a machine. The limit applies to calls through both WebRTC and direct gRPC connection, that means requests can come from modules, the Viam web UI, or other resources.

Solution:

Try to find bottlenecks in scripts or modules that are hitting APIs for the machine in loops. You can check operations and sessions for a machine on its CONTROL tab at the bottom of the screen. To adjust the per-resource limit for modules, you can set the VIAM_RESOURCE_REQUESTS_LIMIT environment variable on your machine to a positive integer higher than the default, 100.

Other common errors

Accidental deletion of machines, locations, organizations, or accounts

If you delete your machine, location, organization, or account by mistake, contact contact@viam.com immediately. They will try to help but cannot guarantee recovery or restoration.

Common module errors

Timed out waiting for module

Full Error: Error adding module - Module X - Error while starting module X: Timed out waiting for module X to start listening. or Resource X timed out during reconfigure

Description: This error occurs when a module fails to start up or reconfigure within the default timeout period (5 minutes to start up, 1 minute to reconfigure). This can happen when there is a slow internet connection, when the module is trying to download a large number of dependencies, or when the module is running on a device with limited compute resources.

Solution:

Try using a faster internet connection.
If you are the module author, consider packaging the module with required dependencies so they don’t need to be downloaded on startup. For Python modules, you can package your module with dependencies by using the PyInstaller steps when uploading your module.
If the problem persists, try setting the VIAM_MODULE_STARTUP_TIMEOUT or VIAM_RESOURCE_CONFIGURATION_TIMEOUT environment variables on your machine to a higher value. You can set these environment variables when you start viam-server, for instance VIAM_MODULE_STARTUP_TIMEOUT=6m30 VIAM_RESOURCE_CONFIGURATION_TIMEOUT=3m0s viam-server -config example-machine.json. Pass a sequence of numbers and time units, for example “6m30s50ms” for a timeout of 6 minutes, 30 seconds, and 50 milliseconds, or “5m” for a timeout of 5 minutes.
If a Go module hangs rather than timing out, see Advanced debugging for Go modules to capture a stack trace.

Common Micro-RDK errors

Unable to properly process stun response IceStunEncodingError

Full Error: unable to properly process stun response IceStunEncodingError

Description: Occurs when a client sends a STUN message to a server and receives one of the following problematic responses:

the response cannot be parsed properly
the response indicates a server state that conflicts with the client’s understanding of the session state

Solution: This error may resolve on its own. If not, look for other related errors in your logs.

Common warnings

Connection establishment failed

Full Warning: warn rdk.networking.signaler.external rpc/wrtc_signaling_answerer.go:389 Connection establishment failed

Description: This error indicates a networking or connection issue.

Solution: See Network Troubleshooting section.

Unable to create PeerConnection with module

Full Warning: Unable to create PeerConnection with module. Ignoring.

Description: Indicates that while the gRPC connection to the module is working as expected, the connection to the module does not support efficient video streaming over WebRTC. Only some Go-based camera modules support optimized video streaming over WebRTC.

You can use any Viam SDK to implement a camera module, but only Go-based modules can access optimized video streaming over WebRTC.

Solution: This warning can be safely ignored.

Network troubleshooting

Check networking:

Check if your machine is showing as online on Viam and check its logs. When viam-server starts it runs a set of network checks which you can view in the logs.

2025-07-16T16:50:57.727Z    INFO    rdk.network-checks    networkcheck/network-check.go:28    Starting network checks
2025-07-16T16:50:57.744Z    INFO    rdk    config/platform.go:181    platform tags    {"tags":"os_version:15"}
2025-07-16T16:50:58.239Z    INFO    rdk.network-checks.udp    networkcheck/network-check-types.go:110    7/7 udp STUN tests succeeded    {"udp_tests":"[{stun_server_url: global.stun.twilio.com:3478, stun_server_addr: 18.156.18.181:3478, ... }]","udp_source_address":"[::]:54092"}

Verify your machine’s internet connection is stable and working properly.
Install netcat and check if you can access turn.viam.com:443 and global.turn.twilio.com:3478:

   nc -zv turn.viam.com 443
   Connection to turn.viam.com port 443 [tcp/https] succeeded!
   nc -zv global.turn.twilio.com 3478
   Connection to global.turn.twilio.com port 3478 [tcp/nat-stun-port] succeeded!

Check if UDP traffic is restricted in any way. You can do this by checking your router settings and talking to your IT department, if applicable.
Restart your machine.
Check your SDK connection:
If you are using API keys to connect, ensure you are using the correct credentials for the machine.
Ensure network checks on viam-server succeed by using the Go SDK’s client.WithNetworkStats() method when connecting and then checking the logs when executing the code:

Try connecting with a different SDK to check whether the issue may be SDK-specific or a code issue.
If you have multiple tabs open with your machine’s page, close all but one. Having too many connections can cause instability on some machines.