Troubleshooting

Troubleshooting#

Common issues and solutions when working with APX.

Common Error Categories#

Schema Validation

  • Buf compilation errors

  • Breaking change detection

  • Policy violations

Versioning

  • SemVer mismatches

  • Go module path errors

  • Tag format issues

Releasing

  • PR creation errors

  • Permission errors

  • CI failures

Code Generation

  • Missing generators

  • Import path issues

  • Output directory problems

Dependencies

  • Version resolution

  • Circular dependencies

  • Cache corruption

Configuration

  • Invalid YAML syntax

  • Path resolution

  • Environment issues

Quick Fixes#

Schema Won’t Compile#

Buf complaints about versioning:

# Ensure proto package ends with vN
package myorg.payments.ledger.v1  # ✓ correct

# Ensure files are under .../vN/ directory
internal/apis/proto/payments/ledger/v1/ledger.proto  # ✓ correct

Missing imports:

# Check buf.work.yaml includes your directories
apx lint --verbose  # shows detailed buf output

Version Errors#

Go mod path errors:

  • v1: module path has no /v1 suffix

  • v2+: module path must end with /v2, /v3, etc.

// ✓ Correct v1 module
module github.com/myorg/apis/proto/payments/ledger

// ✓ Correct v2 module  
module github.com/myorg/apis/proto/payments/ledger/v2

// ✗ Wrong - v1 with suffix
module github.com/myorg/apis/proto/payments/ledger/v1

Release blocked for SemVer:

# Run version suggestion to see recommended bump
apx semver suggest --against=HEAD^
# Update your tag to match (MAJOR/MINOR/PATCH)

Generated Code Issues#

Generated code committed:

# Remove from VCS and add to .gitignore
git rm -r internal/gen/
echo "internal/gen/" >> .gitignore
git commit -m "Remove generated code from VCS"

# Re-run generation in CI only
apx gen go

Import path errors:

# Check go_package option in proto files
option go_package = "github.com/myorg/apis/proto/payments/ledger/v1";

# Verify module path matches
grep "module " go.mod

Diagnostic Commands#

Check APX Status#

# Verify installation
apx --version

# Check configuration
apx config validate

# Show current dependencies
apx list dependencies

# Verify toolchain
apx fetch --dry-run

Debug Schema Issues#

# Verbose linting
apx lint --verbose

# Check specific files
buf lint internal/apis/proto/domain/service/v1

# Validate workspace
buf ls-files

Debug Releasing#

# Dry run release
apx release prepare --dry-run \
  --module-path=internal/apis/proto/domain/service/v1 \
  --canonical-repo=github.com/myorg/apis

Recovery Procedures#

Corrupted Cache#

# Clear APX cache
rm -rf ~/.cache/apx/

# Re-download tools
apx fetch

Failed Release#

# Retry releasing after resolving conflicts
apx release prepare \
  --module-path=internal/apis/proto/domain/service/v1 \
  --canonical-repo=github.com/myorg/apis
apx release submit

# Check canonical repo is up to date and resolve conflicts manually

Breaking Dependencies#

# Rollback to last working version
apx add proto/payments/ledger/v1@v1.1.0  # known good version

# Regenerate code
apx gen go

# Test and update gradually

Log Analysis#

Enable Verbose Output#

# For single command
apx lint --verbose

# For all commands in session
export APX_VERBOSE=true
apx lint  # now verbose by default

Common Log Patterns#

Schema validation failure:

ERROR buf lint failed:
  internal/apis/proto/payments/ledger/v1/ledger.proto:15:1:
    Package name "payments.ledger.v1" should be "myorg.payments.ledger.v1"

Breaking change detected:

ERROR breaking changes detected:
  FILE_SAME_PACKAGE: proto/payments/ledger/v1/ledger.proto:
    Package changed from "myorg.payments.ledger.v1" to "myorg.payments.ledger.v2"

Version mismatch:

ERROR version verification failed:
  Suggested: v1.3.0 (MINOR - new backwards compatible features)
  Tagged: v1.2.1 (PATCH - backwards compatible bug fixes)
  Reason: New RPC method added requires minor version bump

Environment-Specific Issues#

CI/CD Environments#

Missing tools:

# Ensure apx fetch runs in CI
steps:
  - run: apx fetch  # downloads tools
  - run: apx lint

Permission errors:

# Ensure proper GitHub token permissions
permissions:
  contents: read
  pull-requests: write  # for apx release submit
  packages: write       # for package releasing

Container Environments#

Planned

Container-based execution (--use-container / APX_USE_CONTAINER) is planned for a future release. Currently, APX manages reproducible builds via pinned toolchain versions in apx.lock.

Network Restrictions#

Proxy configuration:

# APX respects standard proxy environment variables
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080
apx fetch

Getting Help#

Debug Information#

# Collect debug info for bug reports
apx debug info > debug.txt

# Include in GitHub issues:
# - APX version
# - Operating system  
# - Go version (if relevant)
# - Full error output with --verbose

Community Resources#

Internal Support#

If using APX in an organization:

  • Check with your API governance team

  • Review organization-specific runbooks

  • Consult #api-platform Slack channel (if available)

Next Steps#

Contents