Investigating a GPU Detection Issue in Quip Node Manager v0.2.1-rc9
During testing of Quip Node Manager v0.2.1-rc9 on an Ubuntu system equipped with an NVIDIA GeForce RTX 3060, I encountered an interesting issue:
-
GPU was successfully selected in the UI.
-
config.tomlwas updated correctly. -
However, the node still launched the CPU miner instead of the CUDA miner.
At first glance, this looked like a typical NVIDIA Driver or CUDA installation problem. After tracing the entire startup process, the root cause turned out to be somewhere completely different.
Test Environment
-
Ubuntu 22.04 (VM running on Proxmox)
-
NVIDIA GeForce RTX 3060 (PCI Passthrough)
-
Docker Engine + Docker Compose v2
-
Quip Node Manager v0.2.1-rc9 (built from source)
Symptoms
Inside the Node Manager UI:
-
Select GPU 0
-
Configure GPU Utilization
-
Click Apply & Restart
-
Start the node
The node started successfully, but checking Docker showed:
docker ps
The running miner container was:
quip-cpu
instead of
quip-cuda
The miner log reported:
unsupported-mode
config requires:
gpu=['gpu','cuda']
image supports:
['cpu','qpu']
This indicated that the CPU miner image was attempting to run using a GPU configuration.
First Investigation
The first thing I checked was the runtime configuration:
cat /root/quip-data/data/config.toml
Surprisingly, the GPU configuration had been written correctly:
[gpu]
[cuda.0]
This confirmed two important facts:
-
The UI correctly saved the GPU configuration. -
config.tomlwas not the source of the problem.
The issue had to be somewhere later in the startup pipeline.
Digging Deeper
Looking into the Docker Compose configuration revealed something important.
Quip defines two separate miner services:
cpu
└── quip-miner-cpu
cuda
└── quip-miner-cuda
These services are controlled by Docker Compose Profiles.
Only the active profile is started when the stack launches.
The Root Cause
Although GPU mode was enabled in the UI, Docker Compose was still using the CPU profile.
As a result, the startup flow looked like this:
User enables GPU
│
▼
config.toml updated ✔
│
▼
Compose profile remains CPU ✘
│
▼
quip-miner-cpu starts
│
▼
CPU image receives GPU configuration
│
▼
unsupported-mode
The UI configuration and the runtime environment were no longer synchronized.
Verifying the Hypothesis
To verify the theory, I manually switched Docker Compose to the CUDA profile.
After restarting the stack:
docker compose up -d
The miner container changed to:
quip-cuda
The new logs showed:
NVIDIA GeForce RTX 3060
substrate client connected
GPU mining started successfully.
This confirmed that:
-
NVIDIA Driver was working
-
CUDA was working
-
NVIDIA Container Toolkit was working
-
CUDA miner image was working
The issue was not related to the GPU stack at all.
Instead, Node Manager was not switching Docker Compose from the CPU profile to the CUDA profile after GPU mode was enabled in the UI.
Root Cause Summary
The issue can be summarized as follows:
GPU checkbox enabled
│
▼
config.toml updated ✔
│
▼
Docker Compose profile NOT updated ✘
│
▼
CPU miner starts
│
▼
GPU configuration becomes invalid
This is fundamentally a synchronization issue between:
-
Application configuration
-
Docker Compose runtime
Temporary Workaround
Until an official fix is available, starting Docker Compose with the CUDA profile launches the correct miner image and allows GPU mining to work as expected.
No additional changes to the runtime configuration are required.
Lessons Learned
This investigation serves as a good reminder that not every GPU-related issue is caused by drivers or CUDA.
A few takeaways:
-
Don’t assume the problem is the NVIDIA Driver when GPU acceleration fails.
-
Always verify which container image is actually running.
-
When using Docker Compose Profiles, application settings and runtime profiles must remain synchronized.
-
Debugging layer by layer—from UI → Configuration → Docker Compose → Container → Application—is often the fastest way to identify the true root cause.
Conclusion
In this case, the GPU configuration was written correctly, but the runtime environment continued using the CPU profile.
As a result, the CPU miner attempted to load a GPU configuration, leading to the unsupported-mode error.
I’ve documented the complete investigation process and submitted the findings to the Quip development team. Hopefully, this issue can be addressed in an upcoming release.
If you’re testing Quip Node Manager v0.2.1-rc9 and experience similar behavior, this analysis may help you determine whether the problem is in your GPU environment—or simply in how the runtime profile is being selected.