multica-ai/multica · error

checkout failed: %s

Error message

checkout failed: %s

What it means

The daemon answered the checkout POST with a non-200, non-retryable-busy status, so runRepoCheckout surfaces the raw response body: "checkout failed: <body>". The daemon owns the message — typical bodies include git clone failures, bad refs, disk-full, or invalid workspace/repo state. The CLI makes no attempt to parse it.

Source

Thrown at server/cmd/multica/cmd_repo.go:408

		if err != nil {
			return fmt.Errorf("read daemon checkout response: %w", err)
		}
		if closeErr != nil {
			return fmt.Errorf("close daemon checkout response: %w", closeErr)
		}
		if resp.StatusCode == http.StatusServiceUnavailable && resp.Header.Get("X-Multica-Retryable") == "repo-busy" {
			delay := repoCheckoutRetryDelay(resp.Header.Get("Retry-After"), time.Now())
			timer := time.NewTimer(delay)
			select {
			case <-ctx.Done():
				timer.Stop()
				return fmt.Errorf("connect to daemon: %w", context.Cause(ctx))
			case <-timer.C:
				continue
			}
		}
		if resp.StatusCode != http.StatusOK {
			return fmt.Errorf("checkout failed: %s", string(body))
		}
		break
	}

	var result struct {
		Path       string `json:"path"`
		BranchName string `json:"branch_name"`
	}
	if err := json.Unmarshal(body, &result); err != nil {
		return fmt.Errorf("parse response: %w", err)
	}

	fmt.Fprintf(os.Stdout, "%s\n", result.Path)
	fmt.Fprintf(os.Stderr, "Checked out %s → %s (branch: %s)\n", repoURL, result.Path, result.BranchName)

	return nil
}

View on GitHub (pinned to 2c0912b6ec)

Solutions

  1. Read the body text in the error — it is the daemon's verbatim message and names the exact cause (clone auth, ref, disk).
  2. If it is an auth failure, ensure the daemon has credentials for the repo (SSH key/token in the daemon env, not your shell).
  3. If the ref is wrong, verify it exists (git ls-remote <url> <ref>) and re-run with the correct --ref value.
  4. If workspace_id is empty in the error context, re-run inside a proper daemon task so MULTICA_WORKSPACE_ID is set.

Example fix

# before
multica repo checkout https://github.com/acme/api --ref main-typo
# checkout failed: ref not found: main-typo

# after
git ls-remote https://github.com/acme/api | grep main
multica repo checkout https://github.com/acme/api --ref main
Defensive patterns

Strategy: try-catch

Validate before calling

# pre-flight the repo and ref before asking the daemon
git ls-remote "$URL" "$REF" >/dev/null || { echo 'bad URL or ref' >&2; exit 1; }

Try / catch

if resp.StatusCode != http.StatusOK {
	return fmt.Errorf("checkout failed (%d): %s", resp.StatusCode, string(body)) // keep status for programmatic handling
}

Prevention

When it happens

Trigger: Repository URL unreachable or requires auth (clone fails); requested ref does not exist; the checkout_mode passed via MULTICA_REPO_CHECKOUT_MODE is unsupported; daemon-side disk exhaustion; workspace_id missing or unknown to the daemon.

Common situations: Private repo without credentials in the daemon environment; typo'd branch in repoCheckoutRef; agent environment lost MULTICA_WORKSPACE_ID so workspace_id was sent empty; CI runners with full disks.

Related errors

AI-assisted analysis of multica-ai/multica@2c0912b6ec (2026-08-15). Data as JSON: /api/errors/cf7d9113909ba081. Report an issue: GitHub.