bug(file browser): Timeout error, database lock

[srerickson]

When a workspace is up for more than a day or two, and the coder agent restarts, the file browser agent will fail with an error:

🛠️  Configuring filebrowser 
DB_PATH: .config/filebrowser.db
2026/06/24 06:10:45 No config file used
2026/06/24 06:10:45 Using database: /home/coder/.config/filebrowser.db
Error: timeout

I believe what's happening is the following:

• The coder agent and file browser are alive and well on the workspace
• the coder server triggers an agent restart on the workspace
• the agent startup script tries to start filebrowser with the previous process still running
• Timeout error because the previous process has a lock on home/coder/.config/filebrowser.db

Not sure if I've misconfigured something, or if the file browser startup script needs to be tweaked to check for an existing process.

[linear-code]

ENG-2961

[Harsh9485]

hey @srerickson,
I've a few questions about your experience with this issue,

• is it necessary for the workspace to be running for more then a day to Reproduce the issue?
• could you share more details about your workspace setup? for example, which template are you using?

[srerickson]

My setup is a little particular: The coder workspaces are VMs running in Rancher/Harvest cluster (kubevirt); I've also configured the workspace coder agent to run as a systemd service, which is configured using cloud-config. My templates includes a cloud config file with a section like this:

write_files:
  - path: /opt/coder/init
    permissions: "0755"
    encoding: b64
    content: ${init_script_b64}
  - path: /etc/systemd/system/coder-agent.service
    permissions: "0644"
    content: |
      [Unit]
      Description=Coder Agent
      After=network-online.target
      Wants=network-online.target

      [Service]
      User=${linux_user}
      ExecStart=/opt/coder/init
      EnvironmentFile=/opt/coder/env
      Environment=USE_CAP_NET_ADMIN=true
      Restart=always
      RestartSec=10
      TimeoutStopSec=90
      KillMode=process
      SyslogIdentifier=coder-agent

      [Install]
      WantedBy=multi-user.target

The agent restart is not triggered by the coder server, as I initially thought. The restart is caused by an unattended apt update triggering a restart through systemd.

Preventing the agent restart is relatively straightforward using an entry in /etc/needrestart, but this doesn't address the underlying issue: if the agent service restarts, the file-browser startup results in a timeout error.

[Harsh9485]

I tried to reproduce this issue, and while investigating the root cause, I started to believe that @srerickson's theory is likely correct.

I wasn't able to fully reproduce the original issue, but based on my investigation, I believe this is one of the possible causes.

Technical investigation

When the workspace agent runs the module startup script, it configures and starts File Browser. File Browser opens the BoltDB database and keeps it locked while it is running.

The script then exits after starting File Browser in the background. Since the File Browser process no longer has the startup script as its parent, it is adopted by PID 1 (systemd).

$ ps -o pid,ppid,cmd -p 866,923
    PID    PPID CMD
    866     865 ./coder agent
    923       1 filebrowser

I tried reproducing the issue on an AWS EC2 workspace. In my environment, the Coder agent is running as an independent process rather than a systemd service, so I couldn't simply restart it using:

systemctl restart coder-agent

because no such service exists.

Although I couldn't fully reproduce the original scenario, I was able to reproduce the same timeout error by running File Browser configuration commands while File Browser was already running.

For example:

filebrowser config set --port=13339

returns:

Using database: /home/coder/filebrowser.db
Error: timeout

I also searched the Coder repository but couldn't find any code that manages or cleans up an existing File Browser process before the startup script runs again.

Suggestion

The startup script could be made more resilient by handling this scenario. For example:

• Check whether a File Browser process is already running before calling filebrowser config set.
• Avoid reconfiguring File Browser if it has already been initialized.
• If appropriate, stop the existing File Browser process before starting a new one.

I'm not sure which approach is preferred, but I think the startup script should handle repeated executions more gracefully.