This guide helps you diagnose and resolve common issues when using QWKSync.NET.
Symptoms:
QwkSyncResult shows failureCauses:
TransportId in the profile does not match the transport’s IDSolutions:
<ProjectReference Include="..\..\src\QwkSync.Http\QwkSync.Http.csproj" />
TransportId in your profile exactly matches the transport factory’s ID (case-insensitive):
QwkSyncProfile profile = new QwkSyncProfile
{
Endpoint = new Uri("https://example.com"),
TransportId = "http" // Must match HttpTransportFactory.TransportId
};
QwkSyncClient with a registry that includes your factory. The default client only includes the built-in LocalFolderTransport.Symptoms:
QwkSyncConcurrencyException is thrownCauses:
Solutions:
Ensure previous syncs complete: Wait for the previous sync to complete before starting a new one on the same directories.
Use different directories: If you need concurrent syncs, use different local inbox/outbox directories or different profiles.
Check for hanging operations:
If a sync appears stuck, cancel it using the CancellationToken before starting a new one.
Symptoms:
TimeoutException in issues or as thrown exceptionCauses:
Solutions:
TransferPolicy policy = new TransferPolicy
{
Timeout = TimeSpan.FromMinutes(10) // Adjust as needed
};
Check network connectivity: Verify the endpoint is accessible and responsive.
Symptoms:
Causes:
Solutions:
TransferPolicy.UseAtomicDownloads is true:
TransferPolicy policy = new TransferPolicy
{
UseAtomicDownloads = true // Default, but verify
};
Check for cancellation: If a sync was cancelled mid-transfer, temporary files are cleaned up automatically. Retry the sync.
Symptoms:
Issues list may be empty or indicate no files foundCauses:
Solutions:
PacketDiscovery.QwkSearchPattern and PacketDiscovery.RepSearchPattern match your file naming:
PacketDiscovery discovery = new PacketDiscovery
{
QwkSearchPattern = "*.qwk", // Verify this matches your files
RepSearchPattern = "*.rep"
};
RemoteInboxPath and RemoteOutboxPath are correct for your transport:
PacketDiscovery discovery = new PacketDiscovery
{
RemoteInboxPath = "inbox", // Verify this path exists
RemoteOutboxPath = "outbox"
};
Test with LocalFolderTransport:
Use LocalFolderTransport to verify file discovery locally before testing with remote transports.
Symptoms:
Causes:
Solutions:
Check remote path:
Verify RemoteOutboxPath in PacketDiscovery is correct and writable.
Verify credentials:
If authentication is required, ensure QwkSyncProfile.Credentials is configured appropriately for your transport.
Check file permissions: Ensure your local outbox files are readable.
Test connectivity: Verify you can manually access the remote endpoint.
Symptoms:
SyncAsyncCauses:
QwkSyncConcurrencyException or OperationCanceledException are intentionally not caughtSolutions:
try
{
QwkSyncResult result = await client.SyncAsync(profile, plan, cancellationToken);
}
catch (QwkSyncConcurrencyException ex)
{
// Handle concurrency conflict
Console.WriteLine($"Sync conflict: {ex.Message}");
}
catch (OperationCanceledException)
{
// Handle cancellation
Console.WriteLine("Sync was cancelled");
}
Symptoms:
Causes:
Solutions:
QwkSyncPlan plan = new QwkSyncPlan
{
LocalInboxDirectory = "/path/to/inbox",
LocalOutboxDirectory = "/path/to/outbox",
Progress = new MyProgressReporter()
};
Symptoms:
.tmp files present after syncCauses:
Solutions:
Allow sync to complete or cancel properly:
Ensure syncs are allowed to complete or are cancelled via CancellationToken. Cleanup occurs automatically on normal completion or cancellation.
Manual cleanup: If temporary files remain due to abnormal termination, they can be safely deleted. They are only used during atomic download operations.
Verify directory permissions: Ensure the local inbox directory allows file deletion for cleanup operations.
Provide a log sink to see detailed operation information:
QwkSyncPlan plan = new QwkSyncPlan
{
LocalInboxDirectory = "/path/to/inbox",
LocalOutboxDirectory = "/path/to/outbox",
Log = new ConsoleLogSink() // Implement ISyncLogSink
};
Test with LocalFolderTransport first to isolate transport-specific issues:
QwkSyncProfile profile = new QwkSyncProfile
{
Endpoint = new Uri("file:///path/to/test/folder"),
TransportId = "local-folder"
};
Double-check all profile settings match your environment:
Console.WriteLine($"Endpoint: {profile.Endpoint}");
Console.WriteLine($"TransportId: {profile.TransportId}");
Console.WriteLine($"Credentials: {profile.Credentials}");
Always inspect QwkSyncResult for detailed information:
QwkSyncResult result = await client.SyncAsync(profile, plan, cancellationToken);
Console.WriteLine($"Outcome: {result.Outcome}");
Console.WriteLine($"Issues: {result.Issues.Count}");
foreach (QwkSyncIssue issue in result.Issues)
{
Console.WriteLine($" - {issue.Description}");
}
If you cannot resolve an issue using this guide: