Troubleshoot Connection Setup
Isolate setup failures by method and store side, fix the safest underlying cause, and verify Source and Target access independently before configuration.
Troubleshoot Connection Setup
Section titled “Troubleshoot Connection Setup”Resolve connection blockers before migration configuration so Next-Cart can read and write the supported data required by the selected path.
Connection issues should be resolved before migration configuration. A connection that only partially works can lead to incomplete data-type discovery, missing data, permission errors, or failed validation later.
Prerequisites
Section titled “Prerequisites”Before troubleshooting, confirm that:
| Requirement | Why it matters |
|---|---|
| You can open the purchased migration | Use your own Next-Cart account as the migration owner or through an active Delegate Access grant. |
| The migration path is correct | Setup values must match the selected Source Platform and Target Platform. |
| You know which side failed | Source-side and target-side failures may require different access owners or setup details. |
| You have access to the original credentials or files | You may need to re-copy credentials, regenerate tokens, re-export files, or re-upload KitConnect. |
| You can access the source store and target store directly | Direct access helps confirm whether the issue is with Next-Cart setup values, platform access, or the store itself. |
| You can contact the store owner, hosting owner, or platform admin | Some fixes require permissions you may not have. |
Identify the failed setup area
Section titled “Identify the failed setup area”Start by identifying the visible symptom.
| Symptom | Most likely area to check first |
|---|---|
| Credentials are rejected immediately | API key, token, secret, username, password, client ID, or authorization value. |
| Credential is accepted but data cannot be read | API scopes, permissions, app status, token status, or platform access limits. |
| Store URL is rejected | Public store URL, admin URL, API URL, endpoint URL, or domain format. |
| KitConnect endpoint returns 404 | Web-root placement, actual extracted folder name, domain, or HTTPS path. |
| KitConnect endpoint returns a server error | PHP 5.6 through 8.x compatibility, 755/644 permissions, security rules, hosting restrictions, or incomplete upload. |
| Source files upload but cannot be processed | Wrong file format, incomplete export, renamed files, missing data files, unsupported file structure, or a CSV/XLS/XML Product template mismatch. |
| CSV, XLS, or XML migration shows 0/0 | The upload can be accepted even when Next-Cart cannot recognize Product records from the file structure. Check the exact template before changing migration scope. |
| File transfer fails | SFTP credentials, port, hostname, hosting permissions, file size, or blocked connection. |
| Connection worked before but now fails | Expired token, revoked app, changed password, domain change, store-identity mismatch, firewall rule, or hosting change. |
| The data preview or migrated sample comes from the wrong store | Wrong environment, staging URL, copied credentials from another store, or incorrect purchased migration. |
Troubleshoot the connection
Section titled “Troubleshoot the connection”- Open the migration setup in Next-Cart.
- Confirm the selected Source Platform and Target Platform.
- Identify whether the failed setup belongs to the source store, target store, or uploaded source files.
- Confirm that the setup path shown by Next-Cart matches the expected platform setup.
- Recheck the required values exactly as entered.
- For API or KitConnect setup, optionally use Test Connection to check the affected Source Store or Target Store.
- Read the pop-up notification and store-level status. Not connected identifies the affected platform when access fails.
- If the issue continues, use the relevant issue table below.
- After applying a fix, retry the affected connection. A manual retest is optional; do not change an unrelated working connection.
- Check that the other store’s required setup is complete. For File Upload, confirm that the required files are accepted.
API connection issues
Section titled “API connection issues”| Issue | What to check | Fix |
|---|---|---|
| Invalid token, key, or secret | Credential copied with missing characters, extra spaces, wrong account, or expired token. | Re-copy the value using the platform-specific guide. Regenerate or reauthorize only through that guide’s procedure. |
| Missing permission or scope | Credential lacks access to Products, Categories, Customers, Orders, Reviews, Coupons, Pages, or other selected data types. | Use the exact permissions in the platform-specific guide. A Target connection may require write access; do not substitute a generic read-only scope. |
| Wrong URL | The selected setup provides a URL field, but another URL type or store address was entered. | Use the exact URL type requested for that platform. If no URL field is provided, troubleshoot only the credentials that are actually requested. |
| App or integration disabled | Private app, custom app, API account, or integration is disabled. | Check the app or authorization using the platform-specific procedure before changing credentials. |
| Token expired or revoked | Credential worked before but no longer authenticates. | Follow the platform-specific renewal or authorization procedure and update the required setup values. |
| IP or firewall restriction | Platform or security layer blocks requests from external services. | Review platform security settings, firewall rules, and IP restrictions. |
| Rate limit or temporary platform block | API accepts credentials but fails during data preview or repeated testing. | Wait, reduce repeated tests, then try again. Contact support if the issue persists. |
KitConnect issues
Section titled “KitConnect issues”Inspect the bridge directly only when diagnosing Not connected. Once the affected test returns Connected, no additional browser check is required.
| Issue | What to check | Fix |
|---|---|---|
| KitConnect endpoint returns 404 | The extracted folder is missing from the public web root, the URL uses a different folder name, or the domain points to another document root. | Upload the complete extracted folder without renaming it. Check the web root and use the actual folder name in the example URL https://your-domain.com/kitconnect_xxxxxx/kitconnect.php. |
kitconnect.php is missing | The archive was not fully extracted or an incomplete folder was uploaded. | Re-upload kitconnect.zip, extract it completely, and confirm kitconnect_xxxxxx/kitconnect.php exists using the actual extracted folder name. |
kitconnect.php exists but is blocked in the browser | The public request is being blocked by the web root, WAF, CDN, Cloudflare, or a security plugin. | Confirm the domain/document root and allow the handshake endpoint through the blocking security layer. |
| Permission error | The actual extracted KitConnect folder or PHP file does not have the host-approved permissions. | Use 755 for the directory and 644 for files when supported by the host, or the hosting provider’s secure equivalent. |
| Server error | Unsupported PHP environment, hosting restriction, incomplete upload, or security rule blocks execution. | Confirm PHP 5.6 through 8.x, re-upload the complete folder, and review hosting logs or restrictions. |
| Security system blocks access | Web application firewall, CDN, or bot protection blocks the request. | Temporarily allow the required access or ask the hosting/security owner to review the block. |
| KitConnect remains after completion | Temporary bridge files are still present after migration work is complete. | Remove KitConnect after migration work is complete and verified. |
KitConnect cannot read the store database configuration
Section titled “KitConnect cannot read the store database configuration”First confirm that the selected platform and store are correct and that the complete extracted KitConnect folder is in the public web root used by that store. Do not move, duplicate, or expose application database credentials merely to satisfy the bridge.
If the store uses a customized application layout, relocated configuration, multiple database configurations, or another non-standard bootstrap path, preserve the existing application configuration and submit the affected platform, KitConnect URL, and observed error through Support Tickets. The required correction depends on the actual store structure and should not be guessed from a generic database-file location.
Cloudflare, WAF, or CDN blocks KitConnect
Section titled “Cloudflare, WAF, or CDN blocks KitConnect”Allow the actual KitConnect endpoint through the security layer only as narrowly as required for the migration connection. Confirm the domain, web root, and exact extracted KitConnect folder before changing a firewall rule.
When the security policy requires source-IP allowlisting, obtain the exact addresses required for the affected migration from Support Tickets before creating the rule. Do not guess an IP range or reuse an allowlist from another environment. Keep unrelated WAF, bot, and rate-limit protections enabled.
Nginx blocks the KitConnect endpoint
Section titled “Nginx blocks the KitConnect endpoint”Confirm that the request for kitconnect_xxxxxx/kitconnect.php reaches the correct Nginx server block, public document root, and active PHP handler. Nginx and PHP-FPM socket paths vary by hosting environment, so do not paste a generic fastcgi_pass value or server block without verifying how PHP is already handled on that server.
If direct PHP access is restricted by the hosting configuration, ask the hosting or server administrator to allow the KitConnect endpoint through the existing PHP execution path, then retest the affected store connection.
Source data file issues
Section titled “Source data file issues”| Issue | What to check | Fix |
|---|---|---|
| Required file is missing | Product, customer, order, category, content, or platform-specific file was not exported. | Follow the platform-specific export guide, including technician-assisted preparation when required; do not infer an export action from the filename. |
| File format is wrong | The uploaded file does not match the format required for the selected Source Platform. | Prepare the file again using the matching Source Data Export or Product file guide. |
| Named-platform export was edited manually | Column headers, IDs, relationships, or table names were changed. | Use a fresh export unless Next-Cart specifically instructed the edit. |
| CSV, XLS, or XML Product file structure does not match | Expected filename, field names, field order, row/item structure, or required elements were changed. The file may upload, but migration can report 0/0. | Open the matching CSV, XLS, or XML Product file guide, restore the required Product structure, then upload the corrected file. |
| Export range is incomplete | Orders, customers, or products were filtered unintentionally. | Re-export all records or the full approved date range. |
| Multiple export batches are incomplete | Platform export limit required multiple files, but only one range was uploaded. | Export every required range and keep the files organized. |
| File name no longer identifies the data type | File was renamed in a way that removed its original meaning. | Use clear file names that preserve data type, date range, and platform context. |
| File is unreadable | File is corrupted, partially uploaded, compressed incorrectly, or locked. | Download or export the file again and upload a fresh copy. |
File transfer issues
Section titled “File transfer issues”| Issue | What to check | Fix |
|---|---|---|
| Cannot connect by SFTP | Host, username, password, port, or protocol is incorrect. | Recheck credentials from the hosting provider and use SFTP when available. |
| Host key warning appears | First connection to a server may require host key confirmation. | Confirm the host is correct before accepting. |
| Login succeeds but upload fails | User lacks write permission in the selected folder. | Upload to the correct web root or ask the hosting owner for permission. |
| ZIP upload succeeds but extraction fails | Hosting file manager cannot extract the archive or the archive is incomplete. | Re-upload the ZIP or extract locally and upload the folder. |
| Uploaded files are in the wrong folder | Files were placed outside public_html, www, httpdocs, or the actual store web root. | Move files to the correct web root. |
| Transfer stops midway | Network interruption, file size limit, or hosting timeout. | Retry the upload, use SFTP, or ask the hosting provider to increase upload limits. |
Environment issues
Section titled “Environment issues”| Issue | What to check | Fix |
|---|---|---|
| Wrong source store before the store identity is locked | Credentials or URL belong to a test, staging, or old production store. | Correct the Source Store before advancing from Connect Stores to Configuration. |
| Locked Source Store does not match | The paid migration is already bound to another Source Store URL. | Use the locked Source Store. If a different Source Store is required, use a separate purchased migration for that Source context. |
| Wrong target store before the store identity is locked | Connection points to a staging store while the intended migration should use another Target. | Correct the Target Store before advancing to Configuration. |
| Target Store must change while only the Source URL is locked | No Target URL lock exists yet. | When processing is inactive, connect the valid replacement Target for the purchased Target Platform, rerun the required connection test, and review Configuration before the next migration activity. |
| Locked Target Store does not match | The paid migration is already bound to another Target Store URL. | Use the locked Target Store. If a Source URL is also locked, both store identities remain in force. |
| Connection values cannot be edited | The migration is queued, running, processing, or stopping. | Wait until the active processing state ends before changing an editable connection parameter. |
| URL looks different but may identify the same store | The submitted URL may still match the locked store identity even when its raw text differs. | Use the comparison rules in Store URL Locking and Store Identity before treating it as a different store. |
| Store maintenance is active | Source store or target store is temporarily unavailable. | Wait until maintenance ends and retest. |
| SSL or DNS issue | Domain does not resolve consistently or HTTPS certificate fails. | Resolve DNS or SSL before testing connection again. |
Expected result
Section titled “Expected result”After troubleshooting, you should have one of these outcomes:
- the separate source and target Test Connection results identify and verify the affected side;
- source data files are uploaded and readable;
- KitConnect is reachable at the expected URL;
- the issue is clearly identified and assigned to the correct owner;
- a support ticket is ready with enough details for investigation.
Verify after fixing the issue
Section titled “Verify after fixing the issue”| Check | Pass condition |
|---|---|
| Migration access | Your account is authorized to open the intended purchased migration as the owner or delegated collaborator. |
| Correct migration path | The Source Platform and Target Platform match the purchased service. |
| Correct environment | URLs and credentials point to the intended source store and target store. |
| API setup | Credentials authenticate and provide access to the required data types. |
| KitConnect setup | The affected store returns Connected after any required folder, path, permission, or access correction. A separate browser check is not required after that result. |
| Source files | Uploaded files are complete and readable. For CSV, XLS, and XML, the Product file also matches the exact template and Source records are recognized rather than remaining at 0/0. |
| Source Test Connection | The source test passes when the Source Platform uses API or KitConnect. |
| Target Test Connection | The target connection test passes for the selected Target Platform. |
| Retest result | The same side that failed now passes without changing a connection that already worked. |
When to contact support
Section titled “When to contact support”Contact support if:
- the connection still fails after you apply the relevant checks;
- the platform requires a setup path not shown in your account;
- source data files cannot be exported from the platform;
- KitConnect is blocked by hosting or security rules you cannot change;
- you are unsure whether the setup points to the correct source store or target store;
- the issue affects launch timing.
Include:
- Order # and migration path;
- Source Platform and Target Platform;
- source and target Store URLs when those fields are present;
- setup type shown by Next-Cart;
- separate Source Platform and Target Platform Test Connection results;
- error message or screenshot;
- credential type used, without sharing private token values in plain text;
- affected data type;
- what you expected to happen;
- what happened instead;
- urgency and launch timeline.
File Upload scope and recognition
Section titled “File Upload scope and recognition”For File Upload sources, compare the upload against Supported Files in Connect Stores. A file can be accepted for upload but still fail to produce recognizable Source records when its structure is not valid for the selected platform. For CSV, XLS, or XML, an unexpected 0/0 Product result is a structure-recognition failure, not proof that the connection itself is unavailable.
If a required entity is not listed under Supported Files, add it to the Custom Service scope instead of uploading an unlisted file.
Next Steps
Section titled “Next Steps”| Situation | Go to |
|---|---|
| The connection now passes | Configure Your Migration |
| You need to run the connection test again | Test Platform Connections |
| You need to verify whether a Source or Target Store URL can change | Store URL Locking and Store Identity |
| You need to prepare API credentials again | Set Up an API Connection |
| You need to re-upload source data files | Upload Source Data Files |
| You need to reinstall KitConnect | Install KitConnect |
| SFTP, FTP, web-root placement, upload, or extraction is the problem | Use File Transfer Tools |
| You need help from support | Support Tickets |