Skip to content

Troubleshooting

Common issues and solutions for AAP Bridge.

Connection Issues

Cannot connect to source AAP

Symptoms:

Error: Connection refused to https://source-aap.example.com

Solutions:

  1. Verify the URL is correct in .env
  2. Check network connectivity: curl -I https://source-aap.example.com/api/
  3. Verify the API token is valid and has read scope
  4. Check firewall rules

Cannot connect to target AAP (Platform Gateway)

Symptoms:

Error: 404 Not Found at /api/v2/organizations/

Solution:

Use the host URL only in .env — API paths are auto-discovered:

TARGET__URL=https://target-aap.example.com

On AAP 2.5+, organizations and other shared resources are routed to /api/gateway/v1/ automatically. Legacy /api/v2/ paths in TARGET__URL are stripped but no longer required.

Authentication errors

Symptoms:

Error: 401 Unauthorized

Solutions:

  1. Regenerate API token in AAP UI
  2. Verify token scope matches the instance role:
  3. Source: read-only scope is sufficient; the user must be able to read all resources being migrated
  4. Target: read/write scope with admin-level privileges is required for import, cleanup, and validation
  5. Check token hasn't expired

Database Issues

Cannot connect to PostgreSQL

Symptoms:

Error: connection refused to localhost:5432

Solutions:

  1. Verify PostgreSQL is running: systemctl status postgresql
  2. Check connection string format:
postgresql://user:password@host:port/database
  1. Verify user permissions:
GRANT ALL ON DATABASE aap_migration TO your_user;

State database corruption

Symptoms:

Error: IntegrityError or inconsistent state

Solution:

Reset the state database:

aap-bridge state clear --confirm

Warning

This will require re-running the full migration.

Export Issues

Export runs out of memory

Symptoms:

Error: MemoryError or process killed

Solutions:

  1. Reduce batch sizes in config/config.yaml:
performance:
  batch_sizes:
    hosts: 100  # Reduce from 200
  1. Enable file splitting:
aap-bridge export --records-per-file 500

Export takes too long

Solutions:

  1. Export specific resource types:
aap-bridge export organizations inventories
  1. Increase concurrency (if AAP can handle it):
performance:
  max_concurrent: 20

Import Issues

"SKIPPED - no importer" warning

Symptoms:

Instances: 1 resources (⚠️ SKIPPED - no importer)

Cause: Missing entry in export_import.py method_map.

Solution: This is a code issue. Check docs/developer-guide/adding-resource-types.md for how to add new resource types.

Resource already exists

Symptoms:

Warning: Conflict - organization 'MyOrg' already exists

Behavior: AAP Bridge handles this automatically by:

  1. Comparing existing resource with import data
  2. Updating if different, skipping if identical
  3. Recording the ID mapping

This is not an error - it's idempotent behavior.

Unresolved dependency

Symptoms:

Warning: Unresolved dependency - organization ID 5 not found

Causes:

  1. Dependency wasn't exported
  2. Dependency export failed
  3. Resources exported out of order

Solutions:

  1. Check if the dependency exists in exports
  2. Re-run export for the missing type
  3. Check state database for mapping

Bulk import errors

Symptoms:

Error: Bulk host create failed: 400 Bad Request
Number of hosts exceeds system setting BULK_HOST_MAX_CREATE

Cause: AAP Bridge batch size (performance.batch_sizes.hosts) exceeds the target controller setting BULK_HOST_MAX_CREATE. Stock AAP/AWX installs default this to 100, while the bulk API accepts up to 200 hosts per request. Bridge used to default to 200, which fails on unmodified targets.

Solutions:

  1. Set Bridge batch size to match (or stay below) the target limit:
performance:
  batch_sizes:
    hosts: 100

  1. Or raise the limit on the target: Settings → Bulk Actions → Max number of hosts to allow to be created in a single bulk action (requires admin access).

  2. Verify the target limit before migrating:

aap-bridge config validate --config config/config.yaml --check-connectivity

Bridge now defaults to 100 and auto-caps batch size at import time when it can read BULK_HOST_MAX_CREATE from the target.

Other bulk import failures:

  1. Check for invalid host data (duplicate names, invalid characters)
  2. Reduce batch size further if hosts have large variables payloads (nginx ~1MB body limit):
performance:
  batch_sizes:
    hosts: 50
  1. Check target AAP logs for details

Migration appears stuck polling inventory sources

Symptoms:

  • Import seems frozen after inventory sources (often mistaken for job template creation, which runs later in phase 2)
  • Logs repeatedly show successful GET requests to /api/controller/v2/inventory_sources/<id>/ every few seconds
  • Target UI may already show those sources as healthy while Bridge keeps polling

Cause: After importing inventory sources, Bridge triggers a sync and waits for each inventory_update before continuing (smart/constructed inventories, hosts, then job templates). The wait polls the inventory source object until status leaves active states (pending, waiting, running, never updated, etc.), up to inventory_source_update_job_timeout_seconds (default 3600).

Diagnosis:

  1. Prefer structured sync events over URL-only greps:
grep -E 'inventory_source_sync_poll_state|inventory_source_update_triggered|inventory_source_sync_timeout|inventory_source_sync_failed|inventory_source_sync_expected_job_mismatch' logs/migration.log

  1. In the target UI/API, confirm the source can sync (can_update): SCM sources need a valid source_project; cloud sources need credentials; source=file cannot be updated via the API.

  2. Check whether an inventory update job is actually running or stuck pending (capacity, project sync dependency).

Workarounds:

  1. Lower the wait timeout so a stuck sync fails faster and later phases can proceed when inventory_source_sync_fail_on_job_failure is false (default):
performance:
  inventory_source_update_job_timeout_seconds: 600
  inventory_source_update_poll_interval_seconds: 3
  inventory_source_sync_fail_on_job_failure: false
  1. Fix the source on the target (project sync, credentials), sync it manually in AAP if needed, then resume/rerun import.

Validation Issues

Count mismatch

Symptoms:

Validation failed: Source has 1000 hosts, target has 998

Causes:

  1. Some resources failed to import
  2. Some resources were skipped (duplicates)
  3. Import still in progress

Solutions:

  1. Check import logs for errors
  2. Review skipped resources in state database
  3. Re-run import (idempotent - safe to repeat)

Performance Issues

Migration is slow

Solutions:

  1. Increase concurrency:
performance:
  max_concurrent: 15

  1. Use bulk APIs (enabled by default for hosts)

  2. Check AAP instance capacity - it may be the bottleneck

Rate limiting errors

Symptoms:

Error: 429 Too Many Requests

Solutions:

  1. Reduce rate limit:
performance:
  rate_limit:
    requests_per_second: 20
  1. Reduce concurrency:
performance:
  max_concurrent: 5

Logging and Debugging

Enable debug logging

aap-bridge --log-level DEBUG migrate

Check log files

tail -f logs/aap-bridge.log

Enable payload logging

In config/config.yaml:

logging:
  log_payloads: true
  file_level: DEBUG

Warning

Payload logging may contain sensitive data. Use only for debugging.

Getting Help

If you can't resolve an issue:

  1. Check the GitHub Issues
  2. Search existing issues for similar problems
  3. Open a new issue with:
  4. AAP Bridge version
  5. Source/Target AAP versions
  6. Error messages (scrubbed of secrets)
  7. Relevant log excerpts