What causes "failed to lock Cabana settings %s: %s " in commaai/openpilot?

Check the printed path and errno string: 'Permission denied' -> fix ownership/permissions of the settings dir; 'Read-only file system' -> pick a writable --data_dir.

commaai/openpilot · warning

failed to lock Cabana settings %s: %s

Error message

failed to lock Cabana settings %s: %s

What it means

Printed by the FileLock constructor in cabana's settings.cc when open(O_CREAT) or flock(LOCK_EX) on the settings lock file fails; strerror(errno) names the cause. FileLock guards settings.json against concurrent writers (two cabana instances). On failure it degrades: fd is set to -1, isLocked() returns false, and the caller decides whether to proceed — so this is a warning-level diagnostic, though losing the lock means settings writes can race.

Source

Thrown at openpilot/tools/cabana/settings.cc:59

namespace {

std::filesystem::path settingsFile() {
  return utils::configPath() / "cabana.json";
}

struct LoadedSettings {
  json11::Json::object values;
  bool exists = false;
  bool valid = true;
};

class FileLock {
public:
  explicit FileLock(const std::filesystem::path &path) {
    fd = open(path.c_str(), O_CREAT | O_CLOEXEC, 0600);
    if (fd < 0 || flock(fd, LOCK_EX) < 0) {
      fprintf(stderr, "failed to lock Cabana settings %s: %s\n", path.c_str(), strerror(errno));
      if (fd >= 0) close(fd);
      fd = -1;
    }
  }
  ~FileLock() {
    if (fd >= 0) close(fd);
  }
  bool isLocked() const { return fd >= 0; }

private:
  int fd = -1;
};

LoadedSettings loadSettings() {
  std::ifstream input(settingsFile());
  if (!input) return {};

  const std::string contents{std::istreambuf_iterator<char>(input), std::istreambuf_iterator<char>()};

View on GitHub (pinned to 516ec1e682)

Solutions

Check the printed path and errno string: 'Permission denied' -> fix ownership/permissions of the settings dir; 'Read-only file system' -> pick a writable --data_dir.
Close other running cabana instances before starting a new one if you need the lock honored.
Free disk space if ENOSPC is the reported errno.
If on an exotic FS lacking flock, point cabana's settings/data dir at a local filesystem.

Example fix

# before
cabana   # settings dir owned by root -> 'failed to lock ... Permission denied'

# after
sudo chown -R $USER ~/.comma
cabana

Defensive patterns

Strategy: validation

Validate before calling

import os, fcntl
lock_path = os.path.expanduser('~/.comma/cabana/settings.lock')
os.makedirs(os.path.dirname(lock_path), exist_ok=True)
fd = os.open(lock_path, os.O_CREAT, 0o600)
try:
    fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
    locked = True
except OSError:
    locked = False  # another instance holds it; skip settings writes

Prevention

Ensure the settings directory is writable and owned by the invoking user.
Avoid running two cabana instances sharing one data dir.
Keep settings on a local filesystem that supports flock.

When it happens

Trigger: Two cabana instances starting simultaneously; the settings directory (usually ~/.comma/cabana or the configured data dir) being read-only, full, or owned by another user; or a filesystem without flock support (some network mounts). open failing (fd<0) or flock failing both land here.

Common situations: Running cabana as a different user than the one who owns the config dir, a full disk, NFS/overlay filesystems, or genuinely launching a second cabana while the first is writing settings.

Related errors

AI-assisted analysis of commaai/openpilot@516ec1e682 (2026-08-15). Data as JSON: /api/errors/5e523f9ddb5dd2fb. Report an issue: GitHub.