windmill-labs/windmill · error

Failed to complete GitHub app installation

Error message

Failed to complete GitHub app installation

What it means

After GitHub redirects back to /gh_success, handleGhesFlow POSTs the installation data to the backend to complete a GitHub App installation (GHES flow). If the response is not ok, the page throws with the backend's error text, falling back to this fixed message, and shows a failure toast instead of the success screen.

Source

Thrown at frontend/src/routes/gh_success/+page.svelte:66

			errorMessage = 'Missing or invalid required parameters'
			sendUserToast('Missing or invalid required parameters in the URL', true)
			return
		}

		try {
			const response = await fetch(`/api/w/${workspace_id}/github_app/ghes_installation_callback`, {
				method: 'POST',
				headers: {
					'Content-Type': 'application/json'
				},
				body: JSON.stringify({
					installation_id
				})
			})

			if (!response.ok) {
				const errorData = await response.text()
				throw new Error(errorData || 'Failed to complete GitHub app installation')
			}

			isSuccess = true
			sendUserToast('GitHub app installed successfully', false)
		} catch (error) {
			console.error('Error during GitHub app installation:', error)
			errorMessage = error instanceof Error ? error.message : 'Unknown error occurred'
			sendUserToast(`Error installing GitHub app: ${errorMessage}`, true)
		} finally {
			isLoading = false
		}
	}

	async function handleManagedFlow(url: URL) {
		const workspace_id = url.searchParams.get('workspace_id') || ''
		const installation_id_str = url.searchParams.get('installation_id') || ''
		const account_id = url.searchParams.get('account_id') || ''
		const jwt_token = url.searchParams.get('jwt_token') || ''

View on GitHub (pinned to e474e8803c)

Solutions

1. Retry the GitHub App installation from the integration settings page to get a fresh installation_id
2. Verify the backend's GitHub App credentials (app ID, private key, webhook secret) and GHES URL are correct
3. Check backend logs for the completion endpoint's error body — it is surfaced in the thrown message
4. Ensure the installing user has admin rights on the workspace being linked

Example fix

// before
throw new Error(errorData || 'Failed to complete GitHub app installation')
// after
throw new Error(errorData || `Failed to complete GitHub app installation (HTTP ${response.status})`)

// before POSTing, check the redirect payload is present
const params = new URLSearchParams(window.location.search)
if (!params.get('installation_id')) {
  sendUserToast('Missing installation_id in GitHub redirect — reinstall the app', true)
  return
}

try {
  await handleGhesFlow()
} catch (e) {
  console.error(e)
  sendUserToast(e.message.includes('installation') && e.message !== 'Failed to complete GitHub app installation'
    ? e.message
    : 'GitHub app installation failed — check backend GitHub App settings and retry', true)
}

When it happens

Trigger: Completing a GitHub App installation where the completion endpoint returns 4xx/5xx: bad or expired installation_id/code from the redirect, workspace permission missing, misconfigured GHES URL, or backend error exchanging the installation.

Common situations: GitHub App not granted access to the target workspace; installation cancelled mid-flow leaving an invalid installation_id; wrong GHES base URL configured on the instance; backend GitHub credentials (app id/private key) misconfigured; expired one-time code after a slow redirect.

Related errors

• ${what}: ${supabaseErrorMessage(body) || res.statusText}
• ApiError with mapped HTTP status message (e.g. "Not Found",
• Generic Error: status: ${errorStatus}; status text: ${errorS
• body.error || res.statusText
• Failed to queue flow dependencies job: ${queueResponse.statu

AI-assisted analysis of windmill-labs/windmill@e474e8803c (2026-09-03). Data as JSON: /api/errors/7463b3c1e1b500b4. Report an issue: GitHub.