Skip to content
English
Contact us
  • There are no suggestions because the search field is empty.

Debugging QuiltSync Access Issues

Troubleshoot and resolve QuiltSync access, authentication, and sync issues with step-by-step debugging guidance.

 

Symptoms

QuiltSync may fail to access or sync data due to a variety of observable behaviors:

  • Repeated authentication failures or login prompts
  • Permission denied errors when accessing local files or cloud buckets
  • Hash conflicts or sync failed messages
  • App hangs, fails to sync, or silently stalls
  • Changes not reflected after expected sync events

These symptoms often occur during initial setup, after OS or network changes, or when switching user credentials or environments.

NOTE: Make sure you have first properly installed and launched QuiltSync so it can handle "quilt+s3" URIs, as some operating systems may require explicit permissioning by the user.

Background: QuiltSync File Locations

QuiltSync, our desktop sync application, stores its internal data in two primary locations:

  • QUILT_SYNC_CONTENT Cache — the local file store used for deduplication and syncing user data.
    • Typically located at: ~/QuiltSync; set on first run
  • QUILT_SYNC_CONFIG Cache — stores logs, user credentials, preferences, and sync state.
    • Platform-specific locations:
      • macOS: ~/Library/Application Support/com.quiltdata.quilt-sync
      • Linux: ~/.config/com.quiltdata.quilt-sync
      • Windows: C:\Users\<YourUsername>\AppData\Roaming\com.quiltdata.quilt-sync

These locations are referenced throughout this guide when identifying where to check logs, reset state, or inspect credentials.

Causes

  • Expired or invalid authentication tokens
  • Stale or corrupted local QuiltSync state
  • Conflicting file state or incomplete cleanup from prior installs
  • OS-level issues (e.g., sandboxed filesystem, read-only mounts)

Recommendations

1. Start with the Logs

Inspect logs for root-level error indicators.

Default log locations:

Logs are written in $QUILT_SYNC_CONFIG/logs, e.g.:

  • macOS:
    ~/Library/Application Support/com.quiltdata.quilt-sync/logs
  • Linux:
    ~/.config/com.quiltdata.quilt-sync/logs
  • Windows:
    C:\Users\<YourUsername>\AppData\Roaming\com.quiltdata.quilt-sync\logs

Look for:

  • auth error
  • permission denied
  • hash mismatch
  • sync aborted
  • EOFError, SSL, or network-related failures

2. Check AWS Permissions

Confirm the authenticated user has the required access:

  • Read/write permissions on the target bucket or prefix
  • Correct IAM policies attached to the access role
  • That you're authenticated to the right account/environment

You can force re-authentication by simply deleting your system-specific $QUILT_SYNC_CONFIG/.auth folder. The next time you attempt to access a bucket for a given stack, it will ask you to re-authenticate.

3. Check for Hash or File Conflicts

If logs reference hash conflicts:

  • Verify file contents haven’t changed externally (e.g., outside QuiltSync)
  • Save any modifications in an external folder
  • Remove the package via the QuiltSync GUI, or by manually deleting it from $QUILT_SYNC_CONTENTS

If that doesn't work, you may have identified a bug. Please submit the most recent log to support@quilt.bio.

4. Reset Local State (if needed)

As a last resort—especially if issues persist after permissions/auth refresh:

Delete QuiltSync Local Folders:

  • Content Cache:
    ~/QuiltSync (or platform equivalent)
  • App Configuration:
    • macOS: ~/Library/Application Support/com.quiltdata.quilt-sync
    • Linux: ~/.config/com.quiltdata.quilt-sync
    • Windows: C:\Users\<User>\AppData\Roaming\com.quiltdata.quilt-sync

This will force QuiltSync to reinitialize, generate new tokens, and rescan state.

Tip: Backup these directories before deletion if you want to preserve un-pushed modifications or logs.