When an automation is not working as expected, a systematic approach saves time. Follow these steps in order -- each one narrows down the problem and points you toward the fix.
Step 1: Check Automation Logs
Start by reviewing what the automation reported from its last run.
Where to find logs
In the SureDone UI, navigate to Automations, select the automation in question, and open the Logs tab. Each log entry shows a timestamp, severity level, and message describing what happened at that stage of the run.
What to look for
- Connection status -- Did the automation successfully connect to the remote server or API? Look for "Failed to connect" messages near the top of the log.
- Items processed -- How many items were matched, created, updated, or skipped? If the count is zero when you expected results, there is likely a search, filter, or identifier mismatch.
- Errors and warnings -- Errors stop processing; warnings allow it to continue. Both are worth reviewing.
- Last run status -- Check the status fields:
last_run_success_prod--trueif the last production run succeeded,falseif it failed,nullif it has never run.last_run_success_debug-- Same for the last debug run.
You can also retrieve status via the API:
GET /v3/automations/custom/{id}
The status object in the response includes last_run_start_debug, last_run_finish_debug, last_run_success_debug, debug_files, and their production equivalents.
Step 2: Run in Debug Mode
Debug mode runs the automation through its entire process but does not apply any changes to your production data or send files to external channels.
What debug mode does
- Product imports: Generates the bulk file that would be processed, so you can inspect every row before committing.
- Order imports: Logs the JSON payload of each order update that would be applied, without writing to the database.
- Exports (products and orders): Generates the output file that would be sent to the vendor, without actually sending it.
How to trigger a debug run
Via the API:
GET /v3/automations/custom/{id}/run?debug=true
Optional parameters:
notify=true-- Send an email notification when the debug run completes.email=user@example.com-- Send the notification to this address instead of the account default.
For installed automations, use /v3/automations/installed/{id}/run?debug=true.
Via the UI: Click the Run button on the automation detail page and select the debug option.
Reviewing debug output
After the debug run finishes, retrieve the results:
GET /v3/automations/custom/{id}
Check the status.debug_files array for generated files. Download and inspect them:
- Look for missing data or unexpected blank fields.
- Verify that
vendor_actionsandsuredone_actionsare applied correctly. - Confirm that field mappings produce the values you expect.
debug_files is empty when you expected results, the most likely cause is that no items matched the identifier or search criteria. See Step 5 below.Step 3: Check the Connection
A failed connection is one of the most common reasons for automation failure.
Test the connection
Use the Test Connection button in the UI, or send a validation request to the connection with validate: true in the connection config via the API.
Common connection failures
| Symptom | Likely Cause | Fix |
|---|---|---|
| "Failed to connect to FTP server" | Wrong address, port, or firewall blocking | Verify the hostname and port. Check that your firewall allows outbound connections on the FTP port (default 21). |
| "Failed to connect to SFTP server" | Wrong credentials or key file | Confirm username/password. If using a key file, set is_key_file: true and paste the full key content as the password value. |
| "Failed to connect to HTTP server" | Login endpoint unreachable or wrong credentials | Verify login_address is correct and the credentials work when tested manually (e.g., with curl or Postman). |
| SSL/TLS errors | Certificate verification failing | If the remote server uses a self-signed certificate, set ssl_http: false in the connection config. For production, fixing the certificate is preferred. |
| "Connection timed out" | Server unreachable | Check that the server is online and your network can reach it. Verify there are no VPN or IP-allowlist requirements. |
| FTP passive mode issues | Server returns an internal IP in PASV response | Set use_pasv_address: false in the connection config. This tells the FTP client to ignore the address returned by the server and use the original connection address instead. |
HTTP response codes
If using an HTTP connection, check the HTTP status code in the logs:
- 401 -- Authentication failed. Check username, password, API key, or OAuth token.
- 403 -- Forbidden. The credentials are valid but do not have permission for this resource.
- 404 -- Not found. The URL or endpoint path is wrong.
- 429 -- Rate limited. Configure
throttlesettings to slow down requests. - 500 -- Server error on the remote side. Contact the vendor or check their status page.
Step 4: Verify Field Mapping
Incorrect field mapping is a silent problem -- the automation runs without errors, but the data is wrong or missing.
Check vendor field names
Field names in field_map must match the source file headers or API response keys exactly. Matching is case-sensitive: ItemNumber is not the same as itemnumber.
Check SureDone fields
The SureDone field (the key in field_map) must exist in your account. If it does not, the automation will skip it. To auto-create fields, use the create_custom_fields config option.
Run a small test
Set limit_import to a small number (e.g., 5) to process just a few items during a debug run. This makes it easier to inspect the results without waiting for a full run to complete.
{
"limit_import": 5
}
limit_import only works when payload_multi is false (processing items one at a time via individual API calls). For standard file imports where payload_multi defaults to true, this setting has no effect.Step 5: Check Search and Filter Criteria
If your automation is returning zero items, the search or filter criteria may be wrong.
Validate your search syntax
Make sure the search string follows SureDone's search syntax. Common mistakes include wrong field names, missing colons, or incorrect operators.
Test in the SureDone search UI first
Before putting a search string into an automation config, run it in SureDone's product or order search to confirm it returns the items you expect.
Remember: search overwrites filters
If your config defines both search and filters, the filters array will be replaced by the parsed result of the search string. Use one or the other. See [Common JSON Configuration Errors](30-common-json-errors.md#using-search-and-filters-together) for details.
Check identifier matching
If the search returns items but the automation still shows zero matches, the problem may be the identifier. By default, imports match on guid for items and oid for orders. If your vendor file uses a different field, set the identifier config to match.
Also confirm that the identifier values in the vendor file actually exist in SureDone. Case-sensitive matching is the default; set identifier_case_sensitive: false if your identifiers differ only in case.
Step 6: Validate the Full Config
Use the API validation endpoint to check your config for errors before running:
POST /v3/automations/custom/validate
The response contains:
- errors -- Issues that prevent the automation from running. These must be fixed.
- warnings -- Issues that allow the automation to be saved (in draft mode) but should be addressed before activating.
Common validation errors include missing required fields, invalid field types, unsupported connection types, and invalid cron expressions for the schedule.
Step 7: Reset Status Tables
If you are using diff_update (which is true by default), the automation tracks which items have changed since the last run. Sometimes this tracking data becomes stale, causing items to be skipped even though their data has changed.
When to reset
- After making significant changes to the automation config (e.g., changing
field_mapordiff_fields). - When you suspect
diff_updateis incorrectly skipping items that should be processed. - When switching between debug and production runs and seeing inconsistent results.
How to reset
Via the API:
DELETE /v3/automations/custom/{id}/status?type=debug
DELETE /v3/automations/custom/{id}/status?type=prod
Use type=debug to reset debug tracking, or type=prod to reset production tracking.
Via the UI: Use the Reset Status option on the automation detail page.
After resetting, the next run will treat all matching items as new and process them regardless of previous diff state.
When to Contact Support
If you have worked through all seven steps and the automation still is not behaving correctly, contact SureDone support with the following information:
- Automation ID -- Found in the URL or API response.
- Recent log entries -- Copy the last few log entries showing the error.
- Debug output files -- Attach any debug files that show unexpected results.
- Your config -- Share the automation config (with sensitive values like passwords redacted).
- What you expected vs. what happened -- A clear description of the discrepancy.
This information helps the support team diagnose the issue without back-and-forth.