Migration Troubleshooting

Cause

Invalid or expired API token, insufficient permissions, or network connectivity issues.

Fix

• Verify your API token is still valid and hasn't expired
• Ensure the token has admin-level read access (required for full export)
• Check that your source platform's API URL is correct and reachable
• LaunchDarkly: use a server-side SDK key or a read-only API token with all projects access
• Flagsmith: use an admin API key (not a regular API key)
• Unleash: use an admin token with ‘Client API’ and ‘Admin API’ access

Cause

Exporting hundreds or thousands of flags can exceed default timeouts.

Fix

• Increase the timeout: <InlineCode>--timeout 300</InlineCode> (5 minutes)
• Export flags per project instead of all at once: <InlineCode>--project my-project</InlineCode>
• Use the <InlineCode>--concurrency</InlineCode> flag to parallelize: <InlineCode>--concurrency 5</InlineCode>
• For LaunchDarkly: projects with 500+ flags may need pagination tuning — add <InlineCode>--page-size 100</InlineCode>

Cause

The source platform may have flags in a state that the exporter doesn't handle by default.

Fix

• Check that flags are in active projects/environments (archived/deleted flags are excluded by default)
• Use <InlineCode>--include-archived</InlineCode> to export archived flags
• Verify the export file isn&apos;t empty: <InlineCode>cat export.json | jq &apos;.flags | length&apos;</InlineCode>
• Run <InlineCode>fs-migrate diagnose</InlineCode> to check connectivity and permissions

Cause

The source platform uses targeting rules or operators that don't have a direct FeatureSignals equivalent.

Fix

• Review the preview report to see exactly which rules couldn&apos;t be auto-mapped
• LaunchDarkly: custom rule operators (semver, date comparison) need manual conversion to context attributes with value comparison
• Flagsmith: multivariate flags with 3+ variations may need AB flag type or a custom strategy
• Unleash: custom activation strategies need to be reimplemented as FeatureSignals targeting rules
• Use <InlineCode>--skip-unsupported</InlineCode> to skip problematic flags and handle them separately
• Use <InlineCode>--warn-only</InlineCode> to generate a detailed report without aborting the transform

Cause

Cross-flag dependencies and segment references are platform-specific and may not map cleanly.

Fix

• LaunchDarkly: prerequisite flags are imported as separate flags — you&apos;ll need to recreate the prerequisite relationship manually in FeatureSignals
• Flagsmith: segments are imported as FeatureSignals segments with the same name. Verify the segment conditions match.
• Unleash: segments with complex constraint logic may need manual adjustment. Review each segment in the preview.
• After import, validate segment-based targeting by testing with users that should and shouldn&apos;t match

Cause

A simple on/off flag in the source platform has an implicit or default rule that the exporter interprets as a targeting rule.

Fix

• This is usually correct behavior — the flag had targeting in the source platform
• If you want a pure boolean flag with no rules, edit the transformed JSON before importing: set the rule array to empty
• After import, you can remove rules via the Flag Engine dashboard or via IaC

Cause

One or more flags in the batch failed validation, causing the entire transaction to roll back.

Fix

• Check the error log for the specific flag and validation error that caused the failure
• Common causes: flag key too long, invalid characters in flag key, duplicate flag key, missing required fields
• Fix the problematic flag in the transformed JSON and retry
• Use <InlineCode>--continue-on-error</InlineCode> to import valid flags and skip failures (not recommended for production)
• Validate the transformed JSON before import: <InlineCode>fs-migrate validate --input transformed.json</InlineCode>

Cause

Too many API calls in a short period.

Fix

• Reduce import concurrency: <InlineCode>--concurrency 1</InlineCode>
• Add a delay between requests: <InlineCode>--delay 200</InlineCode> (milliseconds)
• Split the import into smaller batches by project or environment
• Management API rate limit is 100 requests/minute — adjust your import speed accordingly

Cause

Subtle differences in how targeting rules, rollout percentages, or default values are applied between platforms.

Fix

• Check the specific flag and context in the parity report
• Verify the default value matches — FeatureSignals returns the default when no rules match
• Check rollout stickiness: both platforms should use the same attribute (e.g., user_id) for consistent bucketing
• Verify user context attributes: FeatureSignals uses flat key-value context; nested objects may need flattening
• Re-run validation with a larger sample: <InlineCode>--sample-size 5000</InlineCode>
• For percentage rollouts, run validation multiple times to distinguish between random variance and real discrepancies

Cause

Different environment configurations between the two platforms.

Fix

• Check that the environment key mapping is correct in your migration config
• Verify that you imported to the correct target environment
• Ensure production-specific targeting rules were preserved during export
• Compare environment configurations: <InlineCode>fs-migrate diff-env --source-config source.json --target-config target.json</InlineCode>

Cause

Cached flag values from the old platform are still being served.

Fix

• Clear the FeatureSignals SDK cache: restart your application or call the cache invalidation method
• Verify your SDK is connecting to FeatureSignals (not the old platform): check the base URL configuration
• Wait for the old platform&apos;s DNS/TTL to expire if using the same hostname
• Use the OpenFeature provider&apos;s <InlineCode>onContextChange</InlineCode> to force a refresh
• Monitor evaluation traffic to confirm SDKs are hitting FeatureSignals endpoints