> ## Documentation Index
> Fetch the complete documentation index at: https://docs.filefetch.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common issues and solutions for FileFetch

## Authentication Issues

<AccordionGroup>
  <Accordion title="Invalid username, password, security token, or user locked out">
    **Symptoms**:

    * Login fails with "INVALID\_LOGIN" error
    * "User locked out" message

    **Solutions**:

    1. **Verify credentials**: Double-check username, password, and security token
    2. **Password + Token**: Ensure password and token are in separate fields (don't concatenate)
    3. **Reset token**: Get a fresh security token from Salesforce Settings
    4. **Check account status**: Verify your Salesforce account isn't locked or deactivated
    5. **Try web login**: Log in to Salesforce in a browser to verify credentials work
    6. **Contact admin**: If locked, contact your Salesforce administrator
  </Accordion>

  <Accordion title="Connection timeout or network error">
    **Symptoms**:

    * "Connection timeout" error
    * "Network error" or "Failed to connect"

    **Solutions**:

    1. **Check internet**: Verify you have a stable internet connection
    2. **Firewall/VPN**: Ensure firewall or VPN isn't blocking `*.salesforce.com`
    3. **Correct environment**: Verify you selected the right environment (Production/Sandbox/Custom)
    4. **Custom domain**: For My Domain, ensure URL is correct and includes `https://`
    5. **Try browser**: Access Salesforce in a browser to rule out connectivity issues
  </Accordion>

  <Accordion title="API not enabled for user">
    **Symptoms**:

    * "API\_DISABLED\_FOR\_ORG" error
    * "User does not have API access"

    **Solutions**:

    1. **Check profile permissions**: Contact admin to enable "API Enabled" on your user profile
    2. **Permission set**: Admin may need to assign an API-enabled permission set
    3. **Trial org**: Some Salesforce trial orgs don't have API access
  </Accordion>

  <Accordion title="Two-factor authentication (2FA) blocking login">
    **Symptoms**:

    * 2FA prompt appears but can't be completed in FileFetch

    **Solutions**:

    1. **Trusted IP**: Add your IP address to Salesforce Network Access (trusted IPs)
    2. **Contact admin**: Ask admin to whitelist your IP in Salesforce Setup
    3. **OAuth (coming soon)**: OAuth 2.0 support will handle 2FA in future release
  </Accordion>
</AccordionGroup>

## Query Issues

<AccordionGroup>
  <Accordion title="No results returned from query">
    **Symptoms**:

    * Query executes successfully but returns 0 files

    **Solutions**:

    1. **Check filters**: Remove or broaden filters (date range, file type, etc.)
    2. **Verify data exists**: Check in Salesforce that files matching your criteria exist
    3. **Permissions**: Ensure you have access to view the files (sharing rules, etc.)
    4. **Export type**: Verify you're querying the correct type (Files vs Attachments)
    5. **Related object**: If filtering by object, check that files are actually linked to that object
  </Accordion>

  <Accordion title="SOQL syntax error">
    **Symptoms**:

    * "Unexpected token" or "syntax error" in Power Mode

    **Solutions**:

    1. **Check spelling**: Common typos like `SELCT` instead of `SELECT`
    2. **Verify field names**: Ensure field API names are correct (e.g., `Title` not `Name` for Files)
    3. **Check operators**: Use `=` not `==`, proper quoting for strings
    4. **Required fields**: Include `Id` and `ContentDocumentId` (for Files)
    5. **Copy from examples**: Use queries from [SOQL Examples](/reference/soql-examples)
  </Accordion>

  <Accordion title="Query returns 2000 results but I need more">
    **Symptoms**:

    * Query hits Salesforce 2000-row limit

    **Solutions**:

    1. **Add filters**: Use date ranges or other filters to narrow results
    2. **Multiple queries**: Run separate queries for different date ranges
    3. **CSV Import**: If you have a list of IDs, use [CSV Import](/csv-import) instead
    4. **Batch approach**: Export in batches (e.g., monthly) rather than all at once
  </Accordion>

  <Accordion title="Invalid field error in query">
    **Symptoms**:

    * "No such column 'FieldName' on entity 'ContentVersion'"

    **Solutions**:

    1. **Verify field exists**: Check the field exists in Salesforce for that object
    2. **API name**: Use the API name, not the label (e.g., `ContentSize` not `File Size`)
    3. **Custom fields**: Custom fields need `__c` suffix (e.g., `Category__c`)
    4. **Object type**: Some fields only exist on ContentVersion, not Attachment (and vice versa)
    5. **Check reference**: See [Salesforce Objects](/reference/salesforce-objects) for field lists
  </Accordion>
</AccordionGroup>

## CSV Import Issues

<AccordionGroup>
  <Accordion title="No valid IDs found in CSV">
    **Symptoms**:

    * "No valid IDs found in CSV" error

    **Solutions**:

    1. **ID format**: Ensure IDs are 18-character Salesforce IDs
    2. **Correct prefix**: Files should start with `069`, Attachments with `00P`
    3. **Column name**: Include header row with `ContentDocumentId` or `Id`
    4. **No extra spaces**: Remove leading/trailing spaces from IDs
    5. **Check sample**: Test with a known-good ID first
  </Accordion>

  <Accordion title="CSV contains IDs but files not found">
    **Symptoms**:

    * CSV loads but many files show "not found or no access"

    **Solutions**:

    1. **Check permissions**: Verify you have access to those files in Salesforce
    2. **Wrong org**: Ensure IDs are from the org you're currently logged into
    3. **Deleted files**: Files may have been deleted since the CSV was created
    4. **ID type mismatch**: Using ContentDocument IDs when in Attachments mode (or vice versa)
  </Accordion>

  <Accordion title="File too large / CSV won't upload">
    **Symptoms**:

    * CSV file upload fails or is rejected

    **Solutions**:

    1. **Size limit**: CSV must be under 5MB
    2. **Reduce rows**: Split into multiple smaller CSVs
    3. **Remove columns**: Keep only the ID column to reduce file size
    4. **Paste instead**: Try pasting content directly instead of uploading
  </Accordion>
</AccordionGroup>

## Export/Download Issues

<AccordionGroup>
  <Accordion title="Download timeout errors">
    **Symptoms**:

    * "Download timeout after 120 seconds"
    * Some files fail with timeout

    **Solutions**:

    1. **Increase timeout**: Go to Settings → Download Timeout and increase (e.g., 300 seconds)
    2. **Large files**: Very large files may need longer timeout
    3. **Reduce concurrency**: Lower concurrent downloads in Settings (e.g., from 10 to 5)
    4. **Internet speed**: Check your internet connection speed
    5. **Retry failed**: Use Export History to retry failed downloads
  </Accordion>

  <Accordion title="Files downloading as 0 bytes or corrupted">
    **Symptoms**:

    * Downloaded files are empty or won't open

    **Solutions**:

    1. **Check source**: Verify file is valid in Salesforce
    2. **Disk space**: Ensure you have enough free disk space
    3. **Retry download**: Delete the file and re-export
    4. **Antivirus**: Temporarily disable antivirus and retry
    5. **Different folder**: Try exporting to a different location
  </Accordion>

  <Accordion title="Export stops or hangs mid-download">
    **Symptoms**:

    * Progress bar stops moving
    * Export appears frozen

    **Solutions**:

    1. **Wait**: Some files may be large and take time
    2. **Check logs**: Open Export History to see what's happening
    3. **Cancel and retry**: Click Cancel, then retry the export
    4. **Reduce batch size**: Export fewer files at once
    5. **Check connection**: Ensure stable internet throughout export
  </Accordion>

  <Accordion title="Permission denied / Can't write to export folder">
    **Symptoms**:

    * "Permission denied" when trying to save files
    * Files fail to save to disk

    **Solutions**:

    1. **Check folder permissions**: Ensure FileFetch can write to export directory
    2. **Choose different folder**: Change export location in Settings
    3. **Run as admin**: On Windows, try running FileFetch as administrator
    4. **Disk full**: Check if your disk is full
    5. **Path length**: On Windows, ensure export path isn't too long (260 char limit)
  </Accordion>

  <Accordion title="Duplicate files not being handled correctly">
    **Symptoms**:

    * Files with same name overwriting each other
    * Expected duplicates not appearing

    **Solutions**:

    1. **Check duplicate setting**: Verify "Append ID" is enabled in Export Configuration
    2. **Grouped exports**: If grouping by record, duplicates only apply within each folder
    3. **Review summary**: Check `_Export_Summary.txt` for duplicate handling report
    4. **Re-export**: Re-run export with correct duplicate handling setting
  </Accordion>
</AccordionGroup>

## Application Issues

<AccordionGroup>
  <Accordion title="FileFetch won't launch or crashes on startup">
    **Symptoms**:

    * App crashes immediately on launch
    * Window appears then closes

    **Solutions (macOS)**:

    1. **Check Gatekeeper**: Right-click → Open to bypass security
    2. **Reset preferences**: Delete `~/Library/Application Support/app.filefetch.filefetch`
    3. **Reinstall**: Uninstall and download fresh copy
    4. **Console logs**: Check Console.app for crash reports

    **Solutions (Windows)**:

    1. **Run as admin**: Right-click → Run as administrator
    2. **Reinstall**: Uninstall and download fresh installer
    3. **Event Viewer**: Check Windows Event Viewer for errors
    4. **Antivirus**: Whitelist FileFetch in your antivirus
  </Accordion>

  <Accordion title="App freezes or becomes unresponsive">
    **Symptoms**:

    * UI stops responding during export
    * Can't click buttons or interact with app

    **Solutions**:

    1. **Wait**: Large exports may temporarily freeze UI - give it time
    2. **Force quit**: Quit app and restart (exports are saved in history)
    3. **Reduce load**: Export fewer files at once
    4. **Update app**: Check for updates (may fix performance issues)
    5. **Restart computer**: Sometimes helps with resource issues
  </Accordion>

  <Accordion title="Auto-update fails or update won't install">
    **Symptoms**:

    * Update download fails
    * Update won't apply after restart

    **Solutions**:

    1. **Manual download**: Get latest version from [filefetch.app/download](https://filefetch.app/download)
    2. **Full uninstall**: Remove app completely, then install new version
    3. **Check permissions**: Ensure FileFetch has permissions to update itself
    4. **Clear cache**: Delete old update files from temp folder
  </Accordion>

  <Accordion title="High memory or CPU usage">
    **Symptoms**:

    * Computer slows down during exports
    * FileFetch uses lots of RAM/CPU

    **Solutions**:

    1. **Reduce concurrency**: Lower concurrent downloads in Settings
    2. **Close other apps**: Free up system resources
    3. **Smaller batches**: Export fewer files per batch
    4. **Restart app**: Close and reopen FileFetch between large exports
  </Accordion>
</AccordionGroup>

## macOS-Specific Issues

<AccordionGroup>
  <Accordion title="'FileFetch is damaged and can't be opened'">
    **Symptom**: macOS Gatekeeper blocks app

    **Solutions**:

    1. **Right-click → Open**: Bypass Gatekeeper warning
    2. **Terminal command**:
       ```bash theme={null}
       xattr -cr /Applications/FileFetch.app
       ```
    3. **System Settings**: Go to Privacy & Security → allow FileFetch
  </Accordion>

  <Accordion title="Keychain access prompts">
    **Symptom**: Repeated password prompts for keychain

    **Solutions**:

    1. **Click Always Allow**: Choose "Always Allow" instead of "Allow"
    2. **Keychain First Aid**: Run Keychain Access → Keychain First Aid
    3. **Reset keychain**: As last resort, reset login keychain (will lose other passwords)
  </Accordion>
</AccordionGroup>

## Windows-Specific Issues

<AccordionGroup>
  <Accordion title="Windows Defender / SmartScreen warning">
    **Symptom**: Windows blocks installer or app

    **Solutions**:

    1. **Click More Info → Run Anyway**: On SmartScreen warning
    2. **Whitelist**: Add FileFetch to Windows Defender exclusions
    3. **Certificate**: FileFetch is signed - warning is due to newness
  </Accordion>

  <Accordion title="VCRUNTIME140.dll not found">
    **Symptom**: Error about missing DLL file

    **Solutions**:

    1. **Install Visual C++ Redistributable**: Download from [Microsoft](https://aka.ms/vs/17/release/vc_redist.x64.exe)
    2. **Reinstall FileFetch**: After installing redistributable
  </Accordion>
</AccordionGroup>

## Performance Issues

<AccordionGroup>
  <Accordion title="Downloads are very slow">
    **Symptoms**:

    * Exports take much longer than expected
    * Download speed is low

    **Solutions**:

    1. **Check internet speed**: Run speed test to verify connection
    2. **Increase concurrency**: Raise concurrent downloads in Settings (up to 10)
    3. **Network congestion**: Avoid peak hours or shared networks
    4. **VPN**: Disconnect VPN if using one (may slow downloads)
    5. **Salesforce limits**: API may throttle requests during peak times
  </Accordion>

  <Accordion title="Query execution is slow">
    **Symptoms**:

    * Query takes long time to return results

    **Solutions**:

    1. **Add indexes**: Query indexed fields (Id, CreatedDate, etc.)
    2. **Reduce scope**: Use smaller date ranges or LIMIT clause
    3. **Avoid complex queries**: Simplify WHERE conditions
    4. **Check Salesforce**: Query may be slow on Salesforce side
  </Accordion>
</AccordionGroup>

## Getting More Help

If you're still experiencing issues after trying these solutions:

<CardGroup cols={2}>
  <Card title="Contact Support" icon="envelope" href="mailto:support@filefetch.app">
    Email support with detailed description of your issue
  </Card>

  <Card title="Check Export History" icon="clock-rotate-left" href="/export-history">
    Review export logs for error details
  </Card>

  <Card title="FAQ" icon="question" href="/faq">
    Common questions and answers
  </Card>

  <Card title="GitHub Issues" icon="github" href="https://github.com/filefetch/filefetch/issues">
    Report bugs or feature requests
  </Card>
</CardGroup>

### Information to Include When Reporting Issues

When contacting support, please include:

* **FileFetch version**: Found in app footer
* **Operating system**: macOS or Windows version
* **Error message**: Exact error text or screenshot
* **Steps to reproduce**: What you were doing when issue occurred
* **Export Summary**: Attach `_Export_Summary.txt` if relevant
* **Salesforce org type**: Production, Sandbox, or Custom
* **Number of files**: How many files you were trying to export

<Tip>
  The more detail you provide, the faster we can help resolve your issue!
</Tip>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.