Troubleshooting Xferity — Config Validation, Secrets, Transport Trust, Transfer, and Recovery
Troubleshooting
Section titled “Troubleshooting”Troubleshooting Xferity usually means isolating one of these failure areas:
- configuration errors
- secret resolution failures
- trust or authentication problems
- transfer execution failures
- recovery issues such as locking, idempotency, or cleanup
Recommended investigation order
Section titled “Recommended investigation order”Start in this order:
- validate the configuration
- run diagnostics for the affected flow
- review recent logs
- inspect flow status and history
- trace the affected file in audit records
This sequence avoids treating every issue as a transport problem.
Built-in operator tools
Section titled “Built-in operator tools”The current CLI provides:
validatediaglogsflow statusflow history <flow>trace <file>
These tools are usually safer than editing state files or retrying flows blindly.
Common failure categories
Section titled “Common failure categories”OpenPGP provider behavior
Section titled “OpenPGP provider behavior”If a flow uses pgp.provider=auto, troubleshoot in this order:
- confirm whether the native provider succeeded or failed
- check whether the failure was classified as a supported compatibility case
- confirm whether GnuPG was available and fallback was attempted
- confirm cleanup completed for the temporary GnuPG workspace
The current implementation allows only one native attempt and at most one GnuPG attempt.
Enterprise key structure scenario
Section titled “Enterprise key structure scenario”One important compatibility case is compat_enterprise_key_structure.
This usually means:
- the partner key is valid and usable in GnuPG
- the native provider could not handle the key layout reliably
- fallback was allowed because the failure matched a named compatibility case rather than a general runtime error
In operator terms, this is not the same thing as “bad key material”. It usually means “valid enterprise key structure that the native provider did not handle consistently”.
Configuration and validation
Section titled “Configuration and validation”Typical symptoms include startup failure, rejected flow files, or unsupported field errors.
Check:
- YAML field names
- referenced paths
- flow and partner consistency
- hardened-mode restrictions
Secret resolution
Section titled “Secret resolution”If credentials cannot be resolved, a flow may fail before any network action.
Check:
- environment variables
- mounted secret files
- secret-provider bootstrap settings
- hardened-mode plaintext restrictions
Trust verification
Section titled “Trust verification”Protocol trust failures differ by protocol:
- SFTP host verification mismatch
- FTPS certificate validation or fingerprint failure
- AS2 certificate-role or HTTPS trust errors
Check the configured trust model before changing anything.
Transfer execution
Section titled “Transfer execution”These failures include network timeouts, permission errors, unreachable endpoints, and partner-side protocol errors.
Check:
- whether the error is transient or permanent
- network reachability
- remote permissions and paths
- passive-mode expectations for FTPS
Recovery and duplicates
Section titled “Recovery and duplicates”Before rerunning a flow, check:
- whether the file was already processed
- whether a lock is stale or active
- whether a dead-letter artifact exists
- whether rerunning could duplicate partner delivery
Think in terms of scope
Section titled “Think in terms of scope”Identify the scope first:
- service-wide
- flow-wide
- file-specific
- partner-specific
That usually tells you whether the fix belongs in global config, partner config, flow config, or an external dependency.
What not to do first
Section titled “What not to do first”Avoid these common mistakes:
- changing multiple config areas before reproducing the original problem
- bypassing trust verification to force a connection
- deleting lock or state data before confirming what it represents
- rerunning flows repeatedly without checking idempotency and audit history