Troubleshooting
This document lists common errors encountered when working with viam-server
and the Viam app, and provides simple steps to resolve them.
While many common issues and their possible resolutions are presented here, this list is not comprehensive.
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.
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 port22
. - 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 typingyes
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 (likehostname.local
or similar). - Afterwards, when you go to
ssh
to your board again, you will need to accept thessh
host key once more by typingyes
when prompted.
- If so, edit your
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
.
For example, the latest Raspberry Pi OS (Debian GNU/Linux 12 bookworm) includes FUSE version 3 as its default FUSE installation, and requires FUSE version 2 to be installed as well to support 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:sudo add-apt-repository universe sudo apt install libfuse2
If installing
viam-server
on a different Linux distribution, see the AppImage FUSE troubleshooting article for more information.If installing
viam-server
on a Docker image, see I get some errors related to something called “FUSE” - AppImage documentation 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:
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 Viam App Errors
Failed to connect; retrying
Description: The Viam app 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 Viam app.
Solution: Check the following to ensure your machine is accessible to the Viam app:
Is the board component connected to the internet?
Is the
ssh
service configured and running locally on the board?Is the
viam-server
service running locally on the board? You can check by runningsudo systemctl status viam-server
from within anssh
session to the board. It should be listed asactive (running)
.If it is listed as
stopped
orfailed
, you can try restarting it withsudo systemctl start viam-server
.If the command returns the message
Unit viam-server.service could not be found
, be sure you have followed the installation instructions for your board, and then followed the setup instructions.If none of the above succeed in getting
viam-server
up and running, check the logs on your board for any pertinent error messages. Depending on your board’s specific Linux OS, you might use a command similar to the following to show the 50 most recent log messages fromviam-server
. Run this command from within anssh
session to the board:grep 'viam-server' /var/log/syslog | tail -50
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 in the Viam app 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: failed to find camera
Additional Errors: cannot open webcam
, and found no webcams
.
Description: When working with a camera component on the Linux platform, your Linux OS must be able to access the camera properly, and the camera must be configured to use a pixel format that Viam supports.
Solution: On your Linux system, verify each of the following:
Ensure that your Linux OS is able to access your camera:
Run the following command to list compatible camera devices on your system:
v4l2-ctl --list-devices
In the list of camera devices returned, find the entry for your camera. For example, the webcam on the Viam Rover appears as follows:
GENERAL WEBCAM: GENERAL WEBCAM (usb-0000:01:00.0-1.4): /dev/video0 /dev/video1 /dev/media4
The video path for your camera device is the first path listed under that camera, in this case
/dev/video0
.Then, stop
viam-server
, and verify that your Linux OS is able to access that video device properly:v4l2-ctl --stream-count 1 --device /dev/video0
Replace
/dev/video0
in the above command with the video path you determined for your video device above, if different.The command returns successfully (with no output) if Linux is able to successfully communicate with the camera, or errors with
Cannot open device
if there was a problem communicating. If this command errors, you should consult the documentation for your camera and Linux distribution to troubleshoot. If you receive the errorDevice or resource busy
instead, be sure you have stoppedviam-server
first, then re-run the command above.
Ensure that your camera uses a supported pixel format:
First, determine your video path, like
/dev/video0
, following the instructions above.Then, run the following command:
v4l2-ctl --list-formats-ext --device /dev/video0
Replace
/dev/video0
in the above command with the video path you determined for your video device above, if different.The command will return a list of pixel formats your camera supports, such as
MJPG
(also notated asMJPEG
) orYUYV
(also notated asYUY2
). In order to use a camera device with Viam, it must support at least one of the pixel formats supported by Viam. If your camera does not support any of these formats, it cannot be used with Viam.
If you are still having issues with your camera component on the Linux platform, and would like to file an issue, include your machine’s camera debug file contained in the viam-server
as a different user, find the
Error: failed to find the best driver that fits the constraints
Description: When working with a camera component, depending on the camera, you may need to explicitly provide some camera-specific configuration parameters.
Solution: Check the specifications for your camera, and manually provide configuration parameters such as width and height to the camera component configuration page on the Viam app. On the CONFIGURE page, find your camera, then fill in your camera’s specific configuration either using the Show more button to show the relevant configuration options, or the {} (Switch to Advanced) button in the top right of the component panel to enter these attributes manually. Provide at least the width and height values to start.
Known application and plugin conflicts
macOS applications
None at this time.
Windows applications
None at this time.
Linux applications
None at this time.
Browser plugins
Chrome plugin: Allow Right-Click - This Chrome plugin interferes with the Viam app’s ability to configure a service. If you are experiencing issues with the Create Service pane in the Viam app, temporarily disable this plugin until you have saved your configuration in the Viam app.
Have questions, or want to meet other people working on robots? Join our Community Discord.
If you notice any issues with the documentation, feel free to file an issue or edit this file.
Was this page helpful?
Glad to hear it! If you have any other feedback please let us know:
We're sorry about that. To help us improve, please tell us what we can do better:
Thank you!