different-ai/openwork · error · Error

Failed to start GitHub install (${response.status}).

Error message

Failed to start GitHub install (${response.status}).

What it means

Thrown by useStartGithubInstall when POST /v1/connectors/github/install (returnPath payload) returns non-OK. getRequestError throws ReauthRequiredError for 403 reauth payloads or the server message / this fallback otherwise. It means the server could not initiate the GitHub App installation flow (no redirectUrl/state issued).

Source

Thrown at ee/apps/den-web/app/(den)/dashboard/_components/integration-data.tsx:421

export function useStartGithubInstall() {
  const queryClient = useQueryClient();
  const { runReauthableAction } = useOrgDashboard();

  return useMutation({
    mutationFn: async (input: { returnPath: string }): Promise<GithubInstallStartResult> => {
      let result: GithubInstallStartResult | null = null;
      await runReauthableAction("start-github-install", async () => {
      const { response, payload } = await requestJson(
        "/v1/connectors/github/install/start",
        {
          method: "POST",
          body: JSON.stringify({ returnPath: input.returnPath }),
        },
        15000,
      );

      if (!response.ok) {
        throw getRequestError(payload, response, `Failed to start GitHub install (${response.status}).`);
      }

      const item = isRecord(payload) && isRecord(payload.item) ? payload.item : null;
      const redirectUrl = item ? asString(item.redirectUrl) : null;
      const state = item ? asString(item.state) : null;
      if (!redirectUrl || !state) {
        throw new Error("GitHub install start response was incomplete.");
      }

        result = { redirectUrl, state };
      });
      if (!result) {
        throw new Error("GitHub install start response was incomplete.");
      }
      return result;
    },
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: integrationQueryKeys.all });

View on GitHub (pinned to 2b7df46e8a)

Solutions

1. Check the surfaced server message; configure GitHub App credentials (App ID, private key, webhook secret) on the Den server if missing.
2. Re-authenticate on reauth-required errors and retry.
3. Verify the user has permission to manage connectors for the org.
4. Ensure returnPath is a valid in-app route; use a relative path.
5. Check server logs for connector provisioning errors on 5xx.

Example fix

// before
if (!response.ok) {
  throw getRequestError(payload, response, `Failed to start GitHub install (${response.status}).`);
}
// after
if (!response.ok) {
  const err = getRequestError(payload, response, `Failed to start GitHub install (${response.status}).`);
  if (isReauthRequiredError(err)) { redirectToReauth(); return; }
  throw err;
}

if (!githubAppConfigured) return; // server reports connector availability via capabilities/status
if (typeof input.returnPath !== "string" || !input.returnPath.startsWith("/")) return; // relative path only

function isReauth(error: unknown): error is ReauthRequiredError { return error instanceof ReauthRequiredError; }

try {
  await startGithubInstall({ returnPath });
} catch (error) {
  if (isReauthRequiredError(error)) { promptReauth(); return; }
  setConnectError(error instanceof Error ? error.message : "Could not start GitHub install.");
}

When it happens

Trigger: POST /v1/connectors/github/install fails: GitHub App not configured on the Den server (missing App ID/private key), insufficient permissions (401/403), invalid returnPath, or 5xx. 15s timeout.

Common situations: Self-hosted Den with GitHub connector env vars missing; workspace needing reauth; clicking 'Install GitHub' before the connector was provisioned; blocked by org policy restricting connectors.

Related errors

• Failed to complete GitHub installation (${response.status}).
• Failed to fetch latest-mac.yml (${response.status} ${respons
• plugin_ref_not_found
• Managed MCP outbound request exceeded the guarded redirect l
• OIDC discovery failed with ${response.status}. Enter manual

AI-assisted analysis of different-ai/openwork@2b7df46e8a (2026-09-01). Data as JSON: /api/errors/a2d0262dc7ae61c5. Report an issue: GitHub.