coder/.claude/docs/TROUBLESHOOTING.md

Troubleshooting Guide

Common Issues

Database Issues

1. "Audit table entry missing action"

   • Solution: Update enterprise/audit/table.go
   • Add each new field with appropriate action (ActionTrack, ActionIgnore, ActionSecret)
   • Run make gen to verify no audit errors

2. SQL type errors

   • Solution: Use sql.Null* types for nullable fields

   • Set .Valid = true when providing values

   • Example:

     CodeChallenge: sql.NullString{
         String: params.codeChallenge,
         Valid:  params.codeChallenge != "",
     }
     

Testing Issues

1. "package should be X_test"

   • Solution: Use package_test naming for test files
   • Example: identityprovider_test for black-box testing

2. Race conditions in tests

   • Solution: Use unique identifiers instead of hardcoded names
   • Example: fmt.Sprintf("test-client-%s-%d", t.Name(), time.Now().UnixNano())
   • Never use hardcoded names in concurrent tests

3. Missing newlines

   • Solution: Ensure files end with newline character
   • Most editors can be configured to add this automatically

OAuth2 Issues

1. OAuth2 endpoints returning wrong error format

   • Solution: Ensure OAuth2 endpoints return RFC 6749 compliant errors
   • Use standard error codes: invalid_client, invalid_grant, invalid_request
   • Format: {"error": "code", "error_description": "details"}

2. Resource indicator validation failing

   • Solution: Ensure database stores and retrieves resource parameters correctly
   • Check both authorization code storage and token exchange handling

3. PKCE tests failing

   • Solution: Verify both authorization code storage and token exchange handle PKCE fields
   • Check CodeChallenge and CodeChallengeMethod field handling

RFC Compliance Issues

1. RFC compliance failures

   • Solution: Verify against actual RFC specifications, not assumptions
   • Use WebFetch tool to get current RFC content for compliance verification
   • Read the actual RFC specifications before implementation

2. Default value mismatches

   • Solution: Ensure database migrations match application code defaults
   • Example: RFC 7591 specifies client_secret_basic as default, not client_secret_post

Authorization Issues

1. Authorization context errors in public endpoints

   • Solution: Use dbauthz.AsSystemRestricted(ctx) pattern

   • Example:

     // Public endpoints needing system access
     app, err := api.Database.GetOAuth2ProviderAppByClientID(dbauthz.AsSystemRestricted(ctx), clientID)
     

Authentication Issues

1. Bearer token authentication issues

   • Solution: Check token extraction precedence and format validation
   • Ensure proper RFC 6750 Bearer Token Support implementation

2. URI validation failures

   • Solution: Support both standard schemes and custom schemes per protocol requirements
   • Native OAuth2 apps may use custom schemes

General Development Issues

1. Log message formatting errors
   • Solution: Use lowercase, descriptive messages without special characters
   • Follow Go logging conventions

Systematic Debugging Approach

YOU MUST ALWAYS find the root cause of any issue you are debugging YOU MUST NEVER fix a symptom or add a workaround instead of finding a root cause, even if it is faster.

Multi-Issue Problem Solving

When facing multiple failing tests or complex integration issues:

1. Identify Root Causes:

   • Run failing tests individually to isolate issues
   • Use LSP tools to trace through call chains
   • Read Error Messages Carefully: Check both compilation and runtime errors
   • Reproduce Consistently: Ensure you can reliably reproduce the issue before investigating
   • Check Recent Changes: What changed that could have caused this? Git diff, recent commits, etc.
   • When You Don't Know: Say "I don't understand X" rather than pretending to know

2. Fix in Logical Order:

   • Address compilation issues first (imports, syntax)
   • Fix authorization and RBAC issues next
   • Resolve business logic and validation issues
   • Handle edge cases and race conditions last
   • IF your first fix doesn't work, STOP and re-analyze rather than adding more fixes

3. Verification Strategy:

   • Always Test each fix individually before moving to next issue
   • Verify Before Continuing: Did your test work? If not, form new hypothesis - don't add more fixes
   • Use make lint and make gen after database changes
   • Verify RFC compliance with actual specifications
   • Run comprehensive test suites before considering complete

Debug Commands

Useful Debug Commands

Command	Purpose
make lint	Run all linters
make gen	Generate mocks, database queries
go test -v ./path/to/package -run TestName	Run specific test with verbose output
go test -race ./...	Run tests with race detector

LSP Debugging

Go LSP (Backend)

Command	Purpose
mcp__go-language-server__definition symbolName	Find function definition
mcp__go-language-server__references symbolName	Find all references
mcp__go-language-server__diagnostics filePath	Check for compilation errors
mcp__go-language-server__hover filePath line col	Get type information

TypeScript LSP (Frontend)

Command	Purpose
mcp__typescript-language-server__definition symbolName	Find component/function definition
mcp__typescript-language-server__references symbolName	Find all component/type usages
mcp__typescript-language-server__diagnostics filePath	Check for TypeScript errors
mcp__typescript-language-server__hover filePath line col	Get type information
mcp__typescript-language-server__rename_symbol filePath line col newName	Rename across codebase

Common Error Messages

Database Errors

Error: pq: relation "oauth2_provider_app_codes" does not exist

• Cause: Missing database migration
• Solution: Run database migrations, check migration files

Error: audit table entry missing action for field X

• Cause: New field added without audit table update
• Solution: Update enterprise/audit/table.go

Go Compilation Errors

Error: package should be identityprovider_test

• Cause: Test package naming convention violation
• Solution: Use package_test naming for black-box tests

Error: cannot use X (type Y) as type Z

• Cause: Type mismatch, often with nullable fields
• Solution: Use appropriate sql.Null* types

OAuth2 Errors

Error: invalid_client but client exists

• Cause: Authorization context issue
• Solution: Use dbauthz.AsSystemRestricted(ctx) for public endpoints

Error: PKCE validation failing

• Cause: Missing PKCE fields in database operations
• Solution: Ensure CodeChallenge and CodeChallengeMethod are handled

Prevention Strategies

Before Making Changes

1. Read the relevant documentation
2. Check if similar patterns exist in codebase
3. Understand the authorization context requirements
4. Plan database changes carefully

During Development

1. Run tests frequently: make test
2. Use LSP tools for navigation: Avoid manual searching
3. Follow RFC specifications precisely
4. Update audit tables when adding database fields

Before Committing

1. Run full test suite: make test
2. Check linting: make lint
3. Test with race detector: make test-race

Getting Help

Internal Resources

• Check existing similar implementations in codebase
• Use LSP tools to understand code relationships
  • For Go code: Use mcp__go-language-server__* commands
  • For TypeScript/React code: Use mcp__typescript-language-server__* commands
• Read related test files for expected behavior

External Resources

• Official RFC specifications for protocol compliance
• Go documentation for language features
• PostgreSQL documentation for database issues

Debug Information Collection

When reporting issues, include:

1. Exact error message
2. Steps to reproduce
3. Relevant code snippets
4. Test output (if applicable)
5. Environment information (OS, Go version, etc.)