Troubleshoot Connection Setup
Identify the failed connection side, apply the matching correction, and verify access before the Configuration step.
Troubleshoot Connection Setup
Section titled “Troubleshoot Connection Setup”Resolve connection blockers in the Connect Stores step before continuing to the Configuration step. Identify the affected store side and setup method first, then apply only the matching correction.
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 | Incomplete upload, incorrect web-root placement, server routing or execution restrictions, security rules, or hosting restrictions. |
| 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 active migration in the Connect Stores step.
- 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, use Test Connection when it helps verify 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, match the failure to the relevant issue table and follow the corresponding checks.
- After applying a fix, retest only the affected connection when verification is needed; 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. Submit a Support Ticket if the issue persists. |
KitConnect issues
Section titled “KitConnect issues”Start with the exact checks below when KitConnect has been uploaded but the connection still fails.
| Issue | What to check | Fix |
|---|---|---|
| Wrong store URL | The website URL points to another domain, subdomain, or store. | Correct the Source Store or Target Store URL used by the migration. |
| Wrong Source or Target Platform | The selected platform type does not match the store. | Correct the selected Source Platform or Target Platform before continuing. |
| KitConnect was not uploaded | The generated KitConnect folder is absent from the store. | Download the package for the active migration and upload the complete folder. |
Only kitconnect.php was uploaded | The PHP file exists without its generated parent folder. | Upload the complete kitconnect_xxxxxx folder, including the files inside it. |
| Wrong store web root | The KitConnect package is outside the directory that actually serves the store. | Use Locate the Website Web Root Folder to identify the directory that serves the store domain, then move or re-upload the complete KitConnect folder there. |
Invalid secret token | The KitConnect package was downloaded from another account or does not belong to this migration context. | Use the KitConnect package supplied for the intended migration/account. |
| CDN, Cloudflare, WAF, or bot protection blocks the endpoint | Security controls reject the migration request or KitConnect URL. | Allow the Next-Cart migration system or the KitConnect URL through the blocking rule. Use the Cloudflare procedure below when Cloudflare is the blocker. |
| Nginx or Apache blocks direct PHP access | The server configuration prevents public access to kitconnect.php. | Allow the KitConnect URL through the applicable PHP execution path. Use the Nginx/PHP-FPM example below when it matches the server. |
| SSL/TLS certificate expired | HTTPS access fails because the certificate has expired. | Renew the certificate or temporarily use the HTTP version of the URL while the certificate issue is being resolved. |
| Homepage password authentication blocks access | The storefront requires HTTP/basic password authentication before the KitConnect endpoint can be reached. | Temporarily disable the homepage password authentication during the migration process. |
| Remote POST requests are blocked | The web server rejects POST requests from remote servers. | Whitelist the Next-Cart migration system so the required remote POST requests can proceed. |
Cannot get database configuration from KitConnect
Section titled “Cannot get database configuration from KitConnect”If the exact error Cannot get database configuration from the Kitconnect appears, check these causes first:
- Confirm that the selected Source Platform or Target Platform matches the store.
- Confirm that KitConnect can read the store database configuration file.
- If the website database configuration file was moved to another location, create a copy of that file in its original location so KitConnect can read it there.
- If the database configuration file contains multiple database configurations, remove unnecessary configurations that can create a conflict.
- Retry the affected connection.
If the application structure is customized and you cannot apply these checks safely, preserve the observed error and submit a Support Ticket with the affected platform, KitConnect URL, and connection evidence.
Cloudflare, WAF, or CDN blocks KitConnect
Section titled “Cloudflare, WAF, or CDN blocks KitConnect”If Cloudflare blocks the migration request, apply the allowlist procedure to the protected store:
- Open the Cloudflare Dashboard and sign in.
- Select the domain where the store is hosted.
- In the left-hand menu, go to Security > WAF (Web Application Firewall).
- Open Tools or Firewall Rules, depending on the Cloudflare plan/interface.
- Under IP Access Rules, allow these Next-Cart migration system IP addresses:
108.61.242.166,108.61.197.143, and45.32.115.250. - Go to Security > Bots. If Bot Fight Mode blocks the migration requests, disable it for the migration period or add an exception for the listed IPs.
- Retry the affected store connection.
When another WAF or CDN is used, apply the equivalent allow rule for the migration request or KitConnect URL.
Nginx blocks the KitConnect endpoint
Section titled “Nginx blocks the KitConnect endpoint”When the store runs on Nginx and direct access to kitconnect.php is restricted, the following Nginx with PHP-FPM example allows the generated KitConnect URL pattern:
location ~ ^/kitconnect_[a-zA-Z0-9]+/kitconnect\.php$ { include fastcgi_params; fastcgi_pass 127.0.0.1:9000; fastcgi_index kitconnect.php; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;}-
Open the applicable Nginx configuration file, typically under
/etc/nginx/sites-available/or/etc/nginx/conf.d/. -
Add the location block inside the appropriate server block.
-
Adjust
fastcgi_passwhen the server uses a different PHP-FPM socket or upstream. -
Save the configuration.
-
Reload Nginx:
Terminal window sudo systemctl reload nginx
This example assumes Nginx with PHP-FPM. If the server uses CGI, an Apache proxy, custom Nginx routing, or another PHP execution model, ask the system administrator or hosting provider to make kitconnect.php publicly accessible through that environment.
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 Source identity is locked | Credentials or URL belong to a test, staging, or old production store. | Correct the Source Store before the successfully connected setup proceeds to the Configuration step, which would establish the Source URL lock. |
| 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 Target identity is locked | Connection points to a staging store while the intended Migration should use another Target. | Correct the Target Store before the successfully connected setup proceeds to the Configuration step and establishes a Target URL lock under the applicable URL-field rule. |
| 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 the Configuration step 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, routing, 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 submit a Support Ticket
Section titled “When to submit a Support Ticket”Submit a Support Ticket 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 the Connect Stores step. 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 Migration 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 |
| The website web root is unknown or ambiguous | Locate the Website Web Root Folder |
| SFTP, FTP, upload, or extraction is the problem | Use File Transfer Tools |
| You need help from support | Support Tickets |