Troubleshooting

Start with the ticket record and current settings. Use your own ticket ID in place of 42:

dg
dg show 42
dg config

The shell cannot find dg

On native Windows, the release installer writes %LOCALAPPDATA%\Programs\Delegator\bin\dg.exe by default and adds its directory to your user PATH and the PowerShell session that ran the installer. -InstallDir or DG_INSTALL_DIR can select another directory. Check Get-Command dg and dg version. If another terminal cannot find it, close and reopen the terminal application so it inherits the updated user PATH. Running the installer in a child powershell.exe or pwsh process cannot update the parent session’s PATH. To check the default binary directly:

& "$env:LOCALAPPDATA\Programs\Delegator\bin\dg.exe" version

For a custom installation, substitute the directory printed by the installer. If dg runs an older copy, use Get-Command dg -All to locate competing commands. The installer preserves existing PATH order, so an earlier copy can still win. Invoke the intended dg.exe by its full path, then correct the conflicting PATH entry. Do not overwrite your entire PATH.

On macOS/Linux, check command -v dg and dg version. Add the directory printed by the installer to your shell’s PATH if needed.

If you built from source with make install, check go env GOBIN and go env GOPATH. Add the installation directory to PATH: GOBIN when set, otherwise the bin directory inside GOPATH.

See the installation guide for both installers. If guided setup was skipped, cancelled, or failed, run dg init explicitly. The completed installation remains available.

Windows installation or upgrade failed

See the Windows installation guide for installer options, upgrades, and PATH behavior.

• Locked or running executable: close running dg processes normally, including sessions in other terminals, then rerun the same installation command. Windows can prevent replacement of an open dg.exe. A failed replacement preserves the previous binary; do not delete it to force an upgrade.
• Unwritable destination or user PATH: check permissions for the chosen directory and HKCU\Environment\Path. Choose a writable per-user directory with -InstallDir if necessary. A failed PATH write is an installation error and triggers binary rollback. Correct the reported permissions before retrying; administrator privileges and a permanent execution-policy change are not required for the normal per-user installation.
• Release or download unavailable: check HTTPS access to GitHub and the requested version. -Version avoids the latest-release API lookup, but still needs access to release assets. A release must include the matching Windows architecture ZIP and canonical checksum file.
• Checksum rejected or archive missing dg.exe: do not bypass verification. Retry after resolving network or release-asset problems. Download and verification failures leave an existing installation intact.
• Rollback or cleanup failed: retain the backup at the path printed in the error. After resolving locks or permissions, recover the previous binary from that backup if the installer could not restore it. Check any reported user PATH restoration failure separately. Cleanup warnings identify leftover temporary files or backups; confirm the installation works before removing them.

After recovery, check dg version in PowerShell, using the full executable path if command discovery is still wrong. Run dg init if guided setup did not complete.

“sh is not recognized” on Windows

The curl ... | sh command is for macOS/Linux shells. Native Windows PowerShell and Command Prompt do not provide sh. Open PowerShell and use the Windows installation command; installing a Unix shell is not required for the native installer.

If you intend to use WSL, open your WSL distribution and run the Linux command there. Install Git and your coding agent in that same environment. The homepage’s Windows / macOS-Linux selector lets you override browser detection, which cannot tell where you intend to install.

No agent is available

dg agents --all

Check the missing command and its installation hint. Your agent’s ordinary terminal command may exist while its ACP adapter does not. Install the indicated adapter or configure the correct executable with dg agents add, then rerun dg init.

An available executable still needs working authentication and provider access. See agent configuration.

A ticket stays queued

Check these in order:

1. Queue pause: inspect dg; use dg start when you intend to resume scheduling.
2. Capacity: both RUNNING and READY hold slots. Review and accept completed work, or inspect runs and max_runs_per_project with dg config.
3. Dependencies: use dg show 42 and dg map 42. Every prerequisite must be DONE, not merely READY.

Moving a ticket to the top does not bypass these conditions. A failed or cancelled prerequisite needs an explicit decision about how to complete or revise the dependent work.

A run failed

Read the result and run history in dg show 42. Inspect the retained worktree before restarting; useful changes may already exist.

Fix the underlying issue, such as unavailable credentials or a failing project command, then restart:

dg restart 42

Restart reuses the ticket’s branch, worktree, and agent session. Where terminal resume is supported, dg chat 42 lets you continue interactively. After committing completed work, dg finish 42 COMMIT records its commit for review.

If the run hit a time limit, inspect dg config get timeout_minutes. Changing the limit affects subsequent runs. A longer timeout can allow more work and more paid usage; it is not a token budget.

Chat cannot resume

dg chat needs an existing session and worktree, and an agent with a configured terminal resume command. It refuses to attach while the ticket is RUNNING. Use dg agents --all to inspect resume support and dg show 42 to inspect the recorded session.

An accepted ticket’s worktree has been removed, so the normal time to request follow-up changes is before acceptance.

Acceptance is refused

Check the branch, current project HEAD, and worktree status:

dg show 42
worktree=$(dg show 42 --worktree-only)
branch=$(dg show 42 --branch-only)
git -C "$worktree" status --short
git diff HEAD..."$branch"

Run the Git comparison from the project’s primary checkout. Complete the reviewed merge into the intended branch and resolve any uncommitted work in the ticket worktree, then retry dg accept 42.

Do not use --force as a routine workaround: it skips the merge and clean-worktree checks and may discard uncommitted changes. See the full review workflow.

Find local records and logs

By default, Linux and macOS use $XDG_DATA_HOME/delegator, falling back to ~/.local/share/delegator. Windows uses %XDG_DATA_HOME%\delegator, falling back to %LOCALAPPDATA%\delegator. A supplied --data-dir selects a different instance.

That directory contains delegator.db, ticket prose in tickets/, agent logs in runs/, and worktrees in worktrees/. Records and logs do not expire automatically. Logs and ticket text can contain private project information; review them before sharing a diagnostic report.

Manual modification may corrupt the program

Manually modifying the local database or program files may result in delegator failing to run.

Support

If your issue isn’t covered here, please reach out to support@alcubi.ai.