Skip to content
Back to Site

Troubleshoot Connection Setup

Identify the failed connection side, apply the matching correction, and verify access before the Configuration step.

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.

Before troubleshooting, confirm that:

RequirementWhy it matters
You can open the purchased migrationUse your own Next-Cart account as the migration owner or through an active Delegate Access grant.
The migration path is correctSetup values must match the selected Source Platform and Target Platform.
You know which side failedSource-side and target-side failures may require different access owners or setup details.
You have access to the original credentials or filesYou may need to re-copy credentials, regenerate tokens, re-export files, or re-upload KitConnect.
You can access the source store and target store directlyDirect 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 adminSome fixes require permissions you may not have.

Start by identifying the visible symptom.

SymptomMost likely area to check first
Credentials are rejected immediatelyAPI key, token, secret, username, password, client ID, or authorization value.
Credential is accepted but data cannot be readAPI scopes, permissions, app status, token status, or platform access limits.
Store URL is rejectedPublic store URL, admin URL, API URL, endpoint URL, or domain format.
KitConnect endpoint returns 404Web-root placement, actual extracted folder name, domain, or HTTPS path.
KitConnect endpoint returns a server errorIncomplete upload, incorrect web-root placement, server routing or execution restrictions, security rules, or hosting restrictions.
Source files upload but cannot be processedWrong 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/0The 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 failsSFTP credentials, port, hostname, hosting permissions, file size, or blocked connection.
Connection worked before but now failsExpired 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 storeWrong environment, staging URL, copied credentials from another store, or incorrect purchased migration.
  1. Open the active migration in the Connect Stores step.
  2. Confirm the selected Source Platform and Target Platform.
  3. Identify whether the failed setup belongs to the source store, target store, or uploaded source files.
  4. Confirm that the setup path shown by Next-Cart matches the expected platform setup.
  5. Recheck the required values exactly as entered.
  6. For API or KitConnect setup, use Test Connection when it helps verify the affected Source Store or Target Store.
  7. Read the pop-up notification and store-level status. Not connected identifies the affected platform when access fails.
  8. If the issue continues, match the failure to the relevant issue table and follow the corresponding checks.
  9. After applying a fix, retest only the affected connection when verification is needed; do not change an unrelated working connection.
  10. Check that the other store’s required setup is complete. For File Upload, confirm that the required files are accepted.
IssueWhat to checkFix
Invalid token, key, or secretCredential 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 scopeCredential 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 URLThe 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 disabledPrivate 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 revokedCredential worked before but no longer authenticates.Follow the platform-specific renewal or authorization procedure and update the required setup values.
IP or firewall restrictionPlatform or security layer blocks requests from external services.Review platform security settings, firewall rules, and IP restrictions.
Rate limit or temporary platform blockAPI 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.

Start with the exact checks below when KitConnect has been uploaded but the connection still fails.

IssueWhat to checkFix
Wrong store URLThe 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 PlatformThe selected platform type does not match the store.Correct the selected Source Platform or Target Platform before continuing.
KitConnect was not uploadedThe generated KitConnect folder is absent from the store.Download the package for the active migration and upload the complete folder.
Only kitconnect.php was uploadedThe PHP file exists without its generated parent folder.Upload the complete kitconnect_xxxxxx folder, including the files inside it.
Wrong store web rootThe 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 tokenThe 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 endpointSecurity 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 accessThe 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 expiredHTTPS 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 accessThe 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 blockedThe 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:

  1. Confirm that the selected Source Platform or Target Platform matches the store.
  2. Confirm that KitConnect can read the store database configuration file.
  3. 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.
  4. If the database configuration file contains multiple database configurations, remove unnecessary configurations that can create a conflict.
  5. 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.

If Cloudflare blocks the migration request, apply the allowlist procedure to the protected store:

  1. Open the Cloudflare Dashboard and sign in.
  2. Select the domain where the store is hosted.
  3. In the left-hand menu, go to Security > WAF (Web Application Firewall).
  4. Open Tools or Firewall Rules, depending on the Cloudflare plan/interface.
  5. Under IP Access Rules, allow these Next-Cart migration system IP addresses: 108.61.242.166, 108.61.197.143, and 45.32.115.250.
  6. 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.
  7. Retry the affected store connection.

When another WAF or CDN is used, apply the equivalent allow rule for the migration request or KitConnect URL.

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;
}
  1. Open the applicable Nginx configuration file, typically under /etc/nginx/sites-available/ or /etc/nginx/conf.d/.

  2. Add the location block inside the appropriate server block.

  3. Adjust fastcgi_pass when the server uses a different PHP-FPM socket or upstream.

  4. Save the configuration.

  5. 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.

IssueWhat to checkFix
Required file is missingProduct, 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 wrongThe 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 manuallyColumn 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 matchExpected 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 incompleteOrders, customers, or products were filtered unintentionally.Re-export all records or the full approved date range.
Multiple export batches are incompletePlatform 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 typeFile 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 unreadableFile is corrupted, partially uploaded, compressed incorrectly, or locked.Download or export the file again and upload a fresh copy.
IssueWhat to checkFix
Cannot connect by SFTPHost, username, password, port, or protocol is incorrect.Recheck credentials from the hosting provider and use SFTP when available.
Host key warning appearsFirst connection to a server may require host key confirmation.Confirm the host is correct before accepting.
Login succeeds but upload failsUser 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 failsHosting 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 folderFiles were placed outside public_html, www, httpdocs, or the actual store web root.Move files to the correct web root.
Transfer stops midwayNetwork interruption, file size limit, or hosting timeout.Retry the upload, use SFTP, or ask the hosting provider to increase upload limits.
IssueWhat to checkFix
Wrong Source Store before the Source identity is lockedCredentials 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 matchThe 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 lockedConnection 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 lockedNo 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 matchThe 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 editedThe 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 storeThe 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 activeSource store or target store is temporarily unavailable.Wait until maintenance ends and retest.
SSL or DNS issueDomain does not resolve consistently or HTTPS certificate fails.Resolve DNS or SSL before testing connection again.

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.
CheckPass condition
Migration accessYour account is authorized to open the intended purchased migration as the owner or delegated collaborator.
Correct migration pathThe Source Platform and Target Platform match the purchased service.
Correct environmentURLs and credentials point to the intended source store and target store.
API setupCredentials authenticate and provide access to the required data types.
KitConnect setupThe affected store returns Connected after any required folder, path, routing, or access correction. A separate browser check is not required after that result.
Source filesUploaded 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 ConnectionThe source test passes when the Source Platform uses API or KitConnect.
Target Test ConnectionThe target connection test passes for the selected Target Platform.
Retest resultThe same side that failed now passes without changing a connection that already worked.

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.

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.

SituationGo to
The connection now passesConfigure Your Migration
You need to run the connection test againTest Platform Connections
You need to verify whether a Source or Target Store URL can changeStore URL Locking and Store Identity
You need to prepare API credentials againSet Up an API Connection
You need to re-upload source data filesUpload Source Data Files
You need to reinstall KitConnectInstall KitConnect
The website web root is unknown or ambiguousLocate the Website Web Root Folder
SFTP, FTP, upload, or extraction is the problemUse File Transfer Tools
You need help from supportSupport Tickets