Skip to main content
This page covers the most frequent issues users encounter when setting up and running the Raylib Container.

​
Docker Permission Issues

Error Message:
docker: Cannot connect to the Docker daemon... Permission denied.
Cause:This error occurs when your user account doesn’t have permission to access the Docker daemon. You either haven’t added your user to the docker group, or you didn’t log out/log in after adding them.Solutions:
1

Temporary Solution

Use sudo to run Docker commands:
sudo docker run -it --rm raylib_container
2

Permanent Solution (Recommended)

Add your user to the docker group:
sudo usermod -aG docker $USER
After running this command, you must log out and log back in or reboot the system for the group change to take effect.
3

Verify Group Membership

After logging back in, verify you’re in the docker group:
groups | grep docker
Important Note:Depending on the specific configuration of your Linux distribution, there might be situations (for example, when trying to interact with the graphical interface from within a container) where using sudo might still be necessary for some tasks, even if the user is a member of the docker group.

​
Image Reference Issues

Error Message:
docker: invalid reference format
Cause:This error typically occurs when:
  • The image name is misspelled in the docker run command
  • The image doesn’t exist locally
  • There’s a syntax error in the Docker command
Solutions:
1

Verify Image Name

Check that the image name is spelled correctly. The correct name is raylib_container:
docker run -it --rm raylib_container
2

List Available Images

Verify the image exists locally:
docker images
Look for raylib_container in the output.
3

Build the Image

If the image doesn’t exist, build it:
docker build -t raylib_container .

​
Image Not Found

Problem:You’re trying to run a container, but the raylib_container image hasn’t been built yet.Solution:
1

Navigate to Project Directory

Navigate to the directory containing the Dockerfile:
cd /path/to/raylib-container
2

Build the Image

Build the image using one of these commands:
docker build -t raylib_container .
When building the image, Raylib is cloned and compiled directly from the official GitHub repository, ensuring you always have the latest version available.
3

Verify Build

Confirm the image was created:
docker images | grep raylib_container

​
Outdated or Corrupted Image

When to Rebuild:
  • The image seems outdated or corrupted
  • You modified the Dockerfile
  • You want to get a newer version of Raylib
  • You’re experiencing unexplained errors
Solution:
1

Remove Old Image (Optional)

Optionally remove the old image first:
docker rmi raylib_container
2

Rebuild

Rebuild the image:
docker build -t raylib_container .
The --pull flag ensures you get the latest Alpine Linux base image, and --no-cache forces a complete rebuild without using cached layers.

​
Session-Specific Issues

Problem:Graphics were working before, but after rebooting or starting a new graphical session, you get display errors.Cause:The xhost +local:docker command needs to be run in each new graphical session.Solutions:
1

Quick Fix

Run the xhost command again:
xhost +local:docker
2

Permanent Fix

Add the command to your startup scripts so it runs automatically:
# Add to ~/.profile
xhost +local:docker
The specific startup file depends on your desktop environment and login manager. Common options include .profile, .xinitrc, .xprofile, or .bash_profile.

Build docs developers (and LLMs) love

Get started for freeTalk to us