Troubleshooting Synchronization

Synchronization can involve several different areas, including aircraft, aircraft models, hours and cycles, defects, OAuth Applications, FlightLogger Sync settings, endpoints, API keys, webhooks, and sync logs.

Because synchronization is selective, the first step is to understand which data flow you are troubleshooting.

Start by identifying the sync area

Before troubleshooting, identify what is not working.

Is the issue related to:

• Aircraft synchronization?
• Aircraft Model Sync?
• Hours and cycles?
• Defects?
• OAuth API access?
• FlightLogger Sync configuration?
• Webhooks?
• Missing menu items or permissions?
• Maintenance status not updating?

Different sync areas use different configuration and different rules.

Check the account context

FlightLogger Maintenance is account-scoped.

This means sync data must be connected to the correct account.

If the integration uses the wrong account or subdomain, the system may not find the expected aircraft, defects, models, or usage records.

Check:

• Is the integration using the correct account?
• Is the OAuth token requested for the correct subdomain?
• Is the user viewing the correct account?
• Are the records expected to exist in this account?

Account context should be checked early, especially when multiple accounts or environments are used.

Check permissions and OAuth scopes

OAuth API access depends on scopes.

If the integration does not have the required scope, the request may fail.

Relevant scopes include:

• aircraft_read
• aircraft_write
• defects_read
• defects_write
• hours_cycles_read
• hours_cycles_write
• aircraft_models_read
• aircraft_models_write

Common scope-related issues include:

• The integration can read but not write
• The integration can update aircraft but not defects
• Hours/cycles writes fail because hours_cycles_write is missing
• Aircraft model preview does not include old values because read scope is missing
• A request fails with insufficient scope

Review the OAuth Application before troubleshooting the payload.

Check FlightLogger Sync configuration

FlightLogger Sync stores legacy integration configuration used by selected sync services.

Check:

• Is the FlightLogger API key configured?
• Is the endpoint configured?
• Is the endpoint correct?
• Is the endpoint public and reachable?
• Is the endpoint using http or https?
• Is the endpoint private, loopback, link-local, or reserved?
• Is there an account-specific API key?
• Are sync logs being created?

Configured FlightLogger endpoints and webhook URLs must resolve to publicly routable hosts. Private or reserved address ranges are rejected.

Check sync logs

Sync logs are one of the most important troubleshooting tools.

The FlightLogger Sync area can list recent sync log rows.

Sync logs may show:

• Recent sync attempts
• Successful syncs
• Failed syncs
• Short failure summaries
• More detailed error messages for administrators

The detailed error view may include technical information. It is useful for support and implementation teams, but should be reviewed carefully before being copied into customer-facing communication.

Understand the standard API error shape

API errors follow a standard shape.

They include an error code and a human-readable error description.

Common error cases include:

• invalid_token
• insufficient_scope
• not_found
• sync_failed

Use the error code to identify whether the issue is authentication, permission, missing data, or a sync processing problem.

Aircraft is not syncing

If aircraft data is not syncing, check aircraft identity first.

Aircraft endpoints look up aircraft by call sign first and then registration.

Check:

• Does the aircraft exist in FlightLogger Maintenance?
• Does the aircraft exist in FlightLogger?
• Is the call sign correct?
• Is the registration correct?
• Are there formatting differences?
• Is the integration using the expected aircraft identifier?
• Does the integration have aircraft_read or aircraft_write scope?
• Is the request using the correct account?
• Are sync logs showing an error?

If the aircraft cannot be matched, downstream sync flows such as hours/cycles and defects may also fail.

Aircraft Model Sync is not working

Aircraft Model Sync uses configured data source connections.

Check:

• Is there an active aircraft model data source configuration?
• Is the endpoint configured?
• Is the API key configured?
• Is the data source name correct?
• Does the remote data include external_id?
• Does the aircraft model have external_id and external_data_source?
• Does the model’s external data source match an active connection name?
• Does the user have permission to manage integration connections?
• Does the user also have permission to update aircraft models?
• Are recent errors shown on the Aircraft Model Sync page?

Aircraft Model Sync can change aircraft model records, so managing the integration connection alone is not enough. The user also needs permission to update aircraft models.

Hours or cycles are not updating

Hours and cycles sync depends on aircraft matching and flight-log setup.

Check:

• Does the aircraft exist?
• Can the aircraft be found by call sign, registration, or ID?
• Does the integration have hours_cycles_read or hours_cycles_write scope?
• Does the request use a top-level flight payload?
• Is the flight already present and therefore skipped?
• Are flight logs configured on the aircraft?
• Do incoming log names match configured aircraft logs?
• Are reading date and reading time correct?
• Is the data visible under the correct aircraft?
• Do sync logs show an error?

Hours and cycles writes are create-only. If a flight already exists, it may be skipped instead of duplicated.

Defects are not syncing

Defect sync depends on aircraft matching and defect payload structure.

Check:

• Does the aircraft exist?
• Can the aircraft be found by call sign, registration, or ID?
• Does the integration have defects_read or defects_write scope?
• Does the request use a top-level defect object?
• Does the defect include the expected description and reported information?
• Is due date provided in the expected format?
• Is the defect already present under a best-effort match?
• Are sync logs showing a failure?
• Is the user looking at the correct account?

Defect matching is best-effort. Do not treat an external defect ID as a guaranteed permanent shared upsert key.

Defects appear duplicated

If defects appear duplicated, review matching assumptions.

Check:

• Was the same defect sent more than once?
• Did the external defect ID change?
• Did call sign or registration change?
• Was the defect reported under a different aircraft identifier?
• Did the description, date, or reporter data change significantly?
• Are sync logs showing create actions instead of updates?

Because matching is best-effort, duplicates should be investigated before users delete or merge records manually.

Maintenance status is not updating

Maintenance status may depend on more than sync.

If maintenance status looks wrong, check:

• Is aircraft usage data syncing?
• Are hours and cycles visible on the aircraft?
• Are flight logs configured?
• Are counter mappings complete?
• Are recurring maintenance requirements configured?
• Are AMP requirements active and applicable?
• Are defects open or deferred?
• Are work orders open or completed?
• Are compliance items affecting aircraft status?

FlightLogger provides operational input. FlightLogger Maintenance computes maintenance status and due logic.

Webhook issues

If webhooks are used, check:

• Is the webhook URL configured?
• Is the URL public and reachable?
• Is the receiving system expecting JSON?
• Can the receiving system handle retries?
• Can it handle duplicate or redelivered events?
• Is the endpoint protected appropriately?
• Are events treated as untrusted input unless your deployment adds protection?

Webhook delivery is separate from the OAuth token flow.

Missing menu items

If a user cannot see sync settings or actions, the issue may be permissions.

Check:

• Does the user have access to Connect FlightLogger?
• Can the user read integration connections?
• Can the user create or update integration connections?
• Can the user manage sync?
• For Aircraft Model Sync, can the user update aircraft models?
• Is the feature enabled for the account?
• Is the user in the correct account?

Not all users should have access to integration configuration.

What not to assume

• Do not assume that all data is synchronized.

• Do not assume that FlightLogger receives a full mirror of FlightLogger Maintenance.

• Do not assume that creating an OAuth Application configures FlightLogger Sync.

• Do not assume that FlightLogger Sync grants OAuth API access.

• Do not assume that a defect ID is a permanent shared identifier.

• Do not assume that maintenance status is wrong only because sync is wrong.

• Always identify the exact data flow first.

Recommended troubleshooting order

Use this order when troubleshooting sync:

1. Confirm the affected sync area.
2. Confirm account/subdomain context.
3. Confirm user permissions or OAuth scopes.
4. Confirm endpoint and API key configuration.
5. Confirm aircraft matching.
6. Confirm required payload structure.
7. Review sync logs.
8. Check whether data was created, skipped, or rejected.
9. Review related setup, such as flight logs or external IDs.
10. Escalate with sync log details if the issue is still unclear.

Best practices

• Test sync before go-live.

• Use a small set of aircraft first.

• Keep aircraft identifiers consistent.

• Review sync logs regularly during onboarding.

• Document which data flows are enabled.

• Keep API keys and OAuth credentials secure.

• Use only the required OAuth scopes.

• Review aircraft model external IDs and data source names.

• Train users that synchronization is selective.

• Troubleshoot maintenance status separately from raw data sync.

Summary

Synchronization troubleshooting starts with understanding which sync flow is affected.

Most issues relate to account context, missing scopes, endpoint/API key configuration, aircraft matching, missing identifiers, payload structure, or missing setup data such as flight logs.

FlightLogger can provide operational data, but FlightLogger Maintenance remains responsible for maintenance status, due logic, work execution, repair handling, technical records, and compliance documentation.