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 != "",
     }
     

3. Tests passing locally but failing in CI

   • Solution: Check if dbmem implementation needs updating
   • Update coderd/database/dbmem/dbmem.go for Insert/Update methods
   • Missing fields in dbmem can cause tests to fail even if main implementation is correct

Testing Issues

4. "package should be X_test"

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

5. 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

6. Missing newlines

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

OAuth2 Issues

7. 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"}

8. OAuth2 tests failing but scripts working

   • Solution: Check in-memory database implementations in dbmem.go
   • Ensure all OAuth2 fields are properly copied in Insert/Update methods

9. Resource indicator validation failing

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

10. PKCE tests failing

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

RFC Compliance Issues

11. 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

12. 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

13. 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

14. Bearer token authentication issues

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

15. URI validation failures

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

General Development Issues

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

Systematic Debugging Approach

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
   • Check both compilation and runtime errors

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

3. Verification Strategy:

   • Test each fix individually before moving to next issue
   • 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

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

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
• 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.)