Troubleshooting¶
IAM permission errors¶
The tool requires specific IAM permissions for Pinpoint, S3, Customer Profiles, Connect, Kinesis, and KMS. If the tool reports missing permissions:
Review the missing-permissions report generated by the preflight command. Compare your IAM role or profile against the documented minimum permissions policy provided with the tool. Verify that no Service Control Policies (SCPs) restrict the required actions. Re-run the preflight command to confirm the issue is resolved.
Region mismatches¶
The Pinpoint application and Amazon Connect instance must be in the same AWS region. If the tool reports a region mismatch:
Confirm the --region parameter matches the region of both the Pinpoint application and the Connect instance. Verify the region supports Amazon Connect.
Quota limits¶
If the tool reports quota issues during the preflight scan:
Review the quota comparison in the preflight report. Request quota increases through AWS Support before retrying migration.
Note: The tool emits support-ticket-required guidance for quota issues rather than failing mid-run.
Large endpoint exports¶
Export jobs for large datasets (10M+ endpoints) can take significant time. The tool displays the export job ID immediately. Use the --job-id option to check status:
node ./pinpoint-migration-tool.mjs export-endpoints --region <region> --profile <profile> --application-id <app-id> --job-id <job-id>
Interrupted execution¶
The tool supports resumable execution. If a migration is interrupted, re-run the same command. The tool uses progress checkpoints to resume from the last completed step.
Bootstrap and infrastructure errors¶
| Error | Cause | Resolution |
|---|---|---|
StackNotFoundError[^1] |
A migration command ran before bootstrap completed. | Run bootstrap first. |
MissingStackOutputsError |
Bootstrap stack is missing required outputs. | Re-run bootstrap to recreate the stack. |
MigrationStateValidationError |
Migration state file in S3 was manually edited. | Fix or delete the state.json file and re-run. |
KnowledgeBaseNotFoundError |
No Q_MESSAGE_TEMPLATES knowledge base found on the Connect instance. | Configure the knowledge base integration before running template import. |
Template import errors¶
| Error | Cause | Resolution |
|---|---|---|
UnsupportedImportTemplateTypeError |
Template type is not EMAIL or SMS. | Supported types are EMAIL, SMS, VOICE, and PUSH. Remove any other values from the -t flag. |
TemplateConcurrentCreationError |
Another process created the same template during import. | Retry the import. The existing template will be detected and updated. |
Segment import errors¶
| Condition | Cause | Resolution |
|---|---|---|
IMPORT_PLACEHOLDER warning |
Segment is IMPORT-type. A stub is created with a placeholder filter. |
Upload the original customer list via Import from CSV in Amazon Connect after migration. |
NAME_SANITIZED warning |
Segment name contained characters not allowed by Customer Profiles. | The name was modified automatically. Verify the sanitized name in the migration report. |
| Condition | Cause | Resolution |
|---|---|---|
IMPORT_PLACEHOLDER warning |
Segment is IMPORT-type. A stub is created with a placeholder filter. |
Upload the original customer list via Import from CSV in Amazon Connect after migration. |
NAME_SANITIZED warning |
Segment name contained characters not allowed by Customer Profiles. | The name was modified automatically. Verify the sanitized name in the migration report. |
Journey export errors¶
| Error | Cause | Resolution |
|---|---|---|
JourneyCompatibilityError |
Journey contains activities that cannot be converted to a Contact Flow. | Review the error details, remove or modify incompatible activities in Pinpoint, and re-export. |
Logs and reports¶
The tool writes structured output to stdout for every execution: preflight validation reports with pass/fail status for each check, and migration execution summaries with per-resource outcomes.
Exit codes¶
| Exit Code | Meaning |
|---|---|
0 |
Execution completed without errors. |
1 |
One or more validation checks failed, a required dependency was missing, or an incompatible resource was detected. No migration or mutation actions were taken. |
[^1]: