Troubleshooting

"Invalid PAT" or "Authentication Failed"

Connection test fails immediately with authentication error.

Causes:

• PAT expired or revoked
• Incorrect PAT copied (missing characters, extra spaces)
• PAT doesn't have required scopes

Solutions:

1. Verify PAT is active: Go to Azure DevOps → User Settings → Personal Access Tokens and check the status and expiration date.
2. Recreate PAT: Create a new PAT with Build: Read scope and test again.
3. Copy carefully: Use the copy button in Azure DevOps, don't manually select text.
4. Check whitespace: Ensure no leading/trailing spaces when pasting.

"Workspace Not Found"

Connection fails with 404 error for workspace.

Causes:

• Incorrect workspace name (case-sensitive)
• PAT doesn't have access to the workspace
• Workspace visibility restrictions

Solutions:

1. Check workspace URL: Copy the exact name from your Azure DevOps URL: https://dev.azure.com/YOUR-ORG-NAME
2. Verify PAT access: When creating PAT, select "All accessible workspaces" or choose the specific workspace.
3. Test with REST API:

   curl -u :YOUR-PAT https://dev.azure.com/YOUR-ORG/_apis/projects?api-version=7.1

"No Projects/Pipelines Found"

Connection succeeds but no projects or pipelines appear in dropdowns.

Causes:

• PAT lacks Build: Read or Code: Read permissions
• User doesn't have access to projects
• No pipelines exist in the selected project

Solutions:

1. Add scopes: Recreate PAT with Build: Read and Code: Read
2. Check project access: Ensure you're a member of the project in Azure DevOps
3. Verify pipelines exist: Go to Pipelines in Azure DevOps to confirm

Connection Works Initially, Then Fails

Connection stops working after working previously.

Causes:

• PAT expired (typical lifetime: 30-90 days)
• PAT revoked by administrator
• Workspace/project permissions changed

Solutions:

1. Check PAT expiration: Azure DevOps → User Settings → Personal Access Tokens
2. Regenerate or recreate PAT: Click "Regenerate" if available, or create new
3. Update connection: Edit the connection in DeployBrief with new PAT
4. Set reminders: Add calendar reminder 7 days before PAT expiration

401 Unauthorized

API request fails with 401 status code.

Causes:

• Missing or invalid API key
• API key expired or revoked
• Incorrect Authorization header format

Solutions:

1. Verify header format:

   Authorization: Bearer YOUR-API-KEY

2. Check API key status: Go to Settings → API Keys and verify the key is active
3. Test with curl:

   curl -H "Authorization: Bearer YOUR-KEY" https://api.deploybrief.com/api/briefs

4. Regenerate key: Create new API key if old one is compromised

403 Forbidden

API key valid, but request denied.

Causes:

• API key lacks required scope
• Trying to access resource from different workspace
• Workspace membership revoked

Solutions:

1. Check scopes: Ensure API key has necessary permissions (e.g., briefs:write for POST)
2. Verify workspace: Confirm API key belongs to the correct workspace
3. Review audit logs: Check if permissions were recently changed
4. Create scoped key: Generate new API key with required scopes

429 Too Many Requests

Rate limit exceeded.

Causes:

• Exceeding 100 requests/minute per API key
• Multiple CI/CD pipelines using same API key
• Retry logic too aggressive

Solutions:

1. Implement backoff: Wait for Retry-After header value (seconds)
2. Use separate keys: Create individual API keys for each CI/CD pipeline
3. Batch requests: Generate briefs in bulk instead of individual calls
4. Cache responses: Store brief IDs and reuse instead of regenerating

async function generateBriefWithRetry() {
  let delay = 1000; // Start with 1 second
  for (let i = 0; i < 5; i++) {
    const response = await fetch('/api/briefs/generate', { ...});
    if (response.status !== 429) return response;
    await new Promise(r => setTimeout(r, delay));
    delay *= 2; // Double delay each retry
  }
}

"Pipeline Not Found"

Brief generation fails when selecting a pipeline.

Causes:

• Pipeline deleted or renamed in Azure DevOps
• Pipeline moved to different project
• Connection PAT no longer has access

Solutions:

1. Verify pipeline exists: Check Azure DevOps → Pipelines
2. Refresh connection: Reconnect to Azure DevOps to refresh pipeline list
3. Update preset: If using preset, update with new pipeline ID
4. Check permissions: Ensure PAT has Build: Read for the project

Missing or Incorrect Data in Brief

Brief generated but contains placeholder values or incorrect data.

Causes:

• Build/release data not available yet
• Template placeholders not matching available data
• Pipeline run doesn't have expected variables

Solutions:

1. Wait for build to complete: Ensure pipeline run finished before generating brief
2. Check template placeholders: Verify placeholders match available data:
   • {{pipeline.name}} - Pipeline name
   • {{build.number}} - Build number
   • {{build.result}} - Success/Failed/etc.
3. Test with manual generation: Use UI instead of API to see detailed error messages
4. Review audit logs: Check for generation errors in logs

Template or Preset Not Available

Cannot find expected template or preset when generating brief.

Causes:

• Template/preset belongs to different workspace
• User lacks permission to access resource
• Resource was deleted

Solutions:

1. Check workspace context: Ensure you're in the correct workspace
2. Verify permissions: Members can only use templates, not modify them
3. List available resources:

   GET /api/templates
   GET /api/presets

4. Recreate if deleted: Templates and presets can be recreated

GitHub Actions: "API Key Not Found"

Workflow fails to authenticate with DeployBrief API.

Solutions:

1. Add secret: Go to Settings → Secrets and variables → Actions
2. Name exactly: Use DEPLOYBRIEF_API_KEY (case-sensitive)
3. Verify workflow syntax:

   env:
     DEPLOYBRIEF_API_KEY: $${{{ secrets.DEPLOYBRIEF_API_KEY }}}

Azure Pipelines: Connection Timeout

Pipeline hangs or times out when calling DeployBrief API.

Causes:

• Network restrictions on Azure Pipelines agent
• API endpoint unreachable from agent
• Firewall rules blocking traffic

Solutions:

1. Test connectivity: Add step to ping API endpoint
2. Use Microsoft-hosted agents: They have outbound internet access
3. Whitelist IP ranges: If using self-hosted agents with firewall
4. Check proxy settings: Configure proxy if required by your network