VolumeMountError
runpod.errors.VolumeMountError
Stack trace
runpod.errors.VolumeMountError: Failed to mount volume at path '/mnt/data': path does not exist or is inaccessible
File "/app/runpod_client.py", line 45, in start_job
client.start_job(job_config)
File "/usr/local/lib/python3.10/site-packages/runpod/client.py", line 102, in start_job
raise VolumeMountError(f"Failed to mount volume at path '{mount_path}'") Why it happens
This error occurs when the volume mount path specified in the RunPod job configuration does not exist on the host machine or is inaccessible due to permissions or incorrect path syntax. RunPod requires valid, accessible paths to mount volumes into containers.
Detection
Validate all volume mount paths exist and have correct permissions before submitting the job. Add pre-flight checks in your deployment scripts to catch invalid paths early.
Causes & fixes
The specified host path for volume mount does not exist on the machine running the RunPod agent.
Create the missing directory on the host machine or correct the path in your job configuration to point to an existing directory.
The path syntax is incorrect, such as using relative paths or unsupported characters.
Use absolute paths with correct syntax and avoid special characters or environment variables that are not expanded.
Insufficient permissions prevent RunPod from accessing the specified path.
Ensure the RunPod agent user has read/write permissions on the host directory to be mounted.
Attempting to mount a file path instead of a directory as a volume.
Specify a directory path for volume mounts, not a file path.
Code: broken vs fixed
import os
from runpod import RunPodClient
client = RunPodClient()
job_config = {
"volume_mounts": [{"host_path": "./data", "container_path": "/mnt/data"}]
}
# This line triggers VolumeMountError due to relative host_path
client.start_job(job_config)import os
from runpod import RunPodClient
client = RunPodClient()
job_config = {
"volume_mounts": [{"host_path": "/home/user/data", "container_path": "/mnt/data"}]
}
# Fixed: use absolute path for host_path
client.start_job(job_config)
print("Job started successfully with correct volume mount")Workaround
Wrap the job start call in a try/except block catching VolumeMountError, then log the invalid path and fallback to a default valid directory or skip volume mounting temporarily.
Prevention
Implement pre-deployment validation scripts that check all volume mount paths exist and have proper permissions before submitting jobs to RunPod.