mirror of
https://github.com/coder/coder.git
synced 2026-06-02 20:48:20 +00:00
Ethan
e99f7171e4
Move docs linting into the required CI umbrella and reuse the existing `changes` job so docs lint runs when docs or CI files change, plus on `main` as a backstop. This is motivated by the docs lint failures on #25601. That PR touched `.claude/docs/TESTING.md`; the standalone `Docs CI` workflow picked it up because `docs-ci.yaml` used broad `**.md` matching, but local `pnpm lint-docs` and `make lint` did not catch the same file because they only scanned `docs/**` plus root `*.md`. The first failed Docs CI run reported markdownlint errors in `.claude/docs/TESTING.md` (`MD040` and `MD031`), and the next run reported a markdown table formatter failure in the same file. That mismatch is why this PR exists: prevent unrelated PRs from being surprised by stale `.claude/docs/**` lint drift only after they happen to touch one of those files. The local docs scripts now include `.claude/docs/**`, and the old standalone `Docs CI` workflow is removed so we do not maintain separate path-filter logic outside the required CI workflow. > Generated by mux, but reviewed by a human
240 lines
8.9 KiB
Markdown
240 lines
8.9 KiB
Markdown
# 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:
|
|
|
|
```go
|
|
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:
|
|
|
|
```go
|
|
// 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.)
|