Skip to content

Ingest Troubleshooting Guide

This guide covers common errors that occur across all fw ingest commands. For command-specific issues, see the individual command reference pages.

Authentication and Permissions

"Not logged in, please login using fw login"

Cause: No valid API key is configured.

Solution:

  • Run fw login <your_api_key> to authenticate
  • Verify your login status with fw status
  • Get your API key from your Flywheel profile

"Can't perform ingest because of permission errors" (SC04)

Cause: Your user account lacks required permissions on the target group or project.

Solution:

  • Verify you have "Upload Data" and "Create Container" permissions
  • Check your permissions with fw status
  • Contact a group or project administrator to grant permissions
  • Ensure you are logged into the correct Flywheel site

"User does not have the required permissions"

Cause: Insufficient permissions in the target group or project, or in duplicate detection projects.

Solution:

  • Check which permissions are missing in the error message
  • Contact an administrator to grant: "Upload Data", "Create Container", or "Read Data" permissions
  • Verify you are accessing the correct group and project

File and Path Errors

"Invalid source path" (SC01)

Cause: The specified path cannot be accessed or does not exist.

Solution:

  • Verify the path exists: ls /path/to/your/data
  • Check for typos in the path
  • Ensure you have read permissions on the directory
  • Use absolute paths instead of relative paths

"Nothing found to import!"

Cause: No valid files were found in the specified directory after scanning.

Solution:

  • Check that the directory contains the expected file types
  • Verify you are pointing to the correct directory
  • Check subdirectories if files are nested deeper than expected
  • Review include/exclude patterns if using a config file
  • For DICOM: Use --force-scan or --include "*" to parse more files

"Could not open filesystem at ''"

Cause: The filesystem cannot be accessed (may be a permissions issue, network mount problem, or invalid path).

Solution:

  • Verify the path is accessible
  • Check file system permissions
  • For network mounts, ensure the mount is active
  • Try accessing the path directly with ls or cd

"Zero byte file" (SC03)

Cause: One or more files in the source directory have 0 bytes (empty files).

Solution:

  • Identify empty files: find /path/to/data -size 0
  • Remove or exclude empty files from import
  • Check if files were corrupted during transfer
  • This is a warning and won't stop the import, but empty files will be skipped

Project and Container Errors

"The --require-project flag is set and group or project container does not exist" (SC05)

Cause: Using --require-project flag but the specified group or project does not exist.

Solution:

  • Remove the --require-project flag to allow automatic creation
  • Create the group and project in Flywheel before importing
  • Verify group ID and project label are spelled correctly

"Project is locked" (SC08)

Cause: The target project has been locked and does not accept new data.

Solution:

  • Contact a project administrator to unlock the project
  • Verify you are uploading to the correct project
  • Check project settings in the Flywheel web interface

"Project file upload is not enabled" (GE02)

Cause: Attempting to upload files to the project container without enabling the feature.

Solution:

  • Add --enable-project-files flag to your command
  • Note: This is an advanced feature and not commonly used
  • Most files should be uploaded to acquisition containers, not project

"The ingest would import into multiple groups or projects which is not allowed" (GE05)

Cause: The source data maps to multiple different groups or projects.

Solution:

  • Specify explicit group and project with -g and -p flags
  • For template ingest: Ensure template maps all data to a single group/project
  • Split your data into separate import operations if needed

Network and Cloud Storage Errors

"S3 Access denied" (GE04)

Cause: The CLI or ingest cluster cannot access the specified S3 location.

Solution:

  • Verify S3 credentials are configured: S3 Credentials Setup
  • Check bucket name and path are correct
  • Ensure IAM permissions allow read access to the bucket
  • For cluster mode, verify cluster has S3 access configured

Connection Timeout or Upload Failures

Cause: Network issues, very large dataset, or unstable connection.

Solution:

  • Check your internet connection is stable
  • For datasets larger than 100 GB, use Cluster Ingest
  • Verify you can access your Flywheel site in a web browser
  • Contact network administrator if behind a corporate firewall
  • Try uploading a smaller subset of data first to test connectivity
  • Check CLI logs for detailed error information

Configuration Errors

"Compression level needs to be between 0-9"

Cause: Invalid value for --compression-level parameter.

Solution:

  • Use a value between 0 (no compression) and 9 (maximum compression)
  • Default is -1 (automatic)
  • Example: --compression-level 6

"The following errors found during parsing configuration"

Cause: Configuration file or command-line arguments have validation errors.

Solution:

  • Review the specific validation errors listed
  • Check YAML syntax if using a config file
  • Verify all required fields are present
  • Ensure field values are the correct type (string, number, boolean)

"--config-file not allowed with argument --no-config"

Cause: Conflicting configuration arguments.

Solution:

  • Remove either --config-file or --no-config
  • Use --config-file to specify a config file
  • Use --no-config to ignore default config file locations

"--debug not allowed with argument --quiet"

Cause: Conflicting logging level arguments.

Solution:

  • Remove either --debug or --quiet
  • Use --debug for verbose logging
  • Use --quiet to suppress non-error output

De-identification Errors

"Invalid deid profile"

Cause: The specified de-identification profile has validation errors.

Solution:

  • Check the deid profile YAML syntax
  • Verify all DICOM field names are correct
  • Review de-identification documentation
  • Test profile with a small dataset first

"Unknown deid profile"

Cause: The specified deid profile name does not exist.

Solution:

  • Check available profiles in Flywheel web interface
  • Verify profile name spelling (names are case-sensitive)
  • Ensure profile has been created and saved
  • Use --deid-profile minimal for built-in minimal profile

"De-Identification Logging feature is enabled but no De-Id profile is configured" (GE07)

Cause: Project has deid logging enabled but no deid profile is configured for the import.

Solution:

  • Specify a profile: --de-identify --deid-profile <profile_name>
  • Or configure a deid profile on the project in Flywheel
  • Or disable deid logging if not needed

Task and Worker Errors

"Task failed, retrying later"

Cause: A background task failed and will be retried automatically.

Solution:

  • Wait for the retry to complete
  • If retries continue failing, check the specific error message
  • Review CLI logs for detailed error information
  • May indicate network issues, permissions problems, or data issues

"Maximum number of retries has been reached!"

Cause: A task failed repeatedly and exhausted all retry attempts.

Solution:

  • Check CLI logs to identify the specific failure
  • Common causes: persistent network issues, invalid data, insufficient permissions
  • Fix the underlying issue and restart the import
  • For large imports, consider using Cluster Ingest for better reliability

Cluster Mode Errors

"Couldn't determine the ingest URL"

Cause: Attempting to follow or abort a cluster ingest without specifying the ingest URL.

Solution:

  • Specify the ingest URL with --ingest-url argument
  • The URL is displayed when starting the cluster ingest
  • Format: https://<cluster>/ingests/<ingest_id>

"The provided url should have the following format"

Cause: Ingest URL does not match the expected format.

Solution:

  • Verify URL format: https://<cluster>/ingests/<ingest_id>
  • Copy the URL exactly as provided when starting the ingest
  • Ensure no extra characters or spaces

"Ingest already completed/aborted/failed"

Cause: Attempting to abort an ingest that has already finished.

Solution:

  • Check ingest status before attempting to abort
  • If ingest failed, review logs to determine cause
  • If ingest completed, no action needed

Getting More Help

If you encounter an error not listed here:

  1. Check command-specific troubleshooting:
  2. fw ingest dicom
  3. fw ingest bids
  4. fw ingest folder
  5. fw ingest template

  6. fw ingest project

  7. Find detailed error information:

  8. Locate your CLI logs
  9. Logs contain detailed error messages and stack traces

  10. Include logs when contacting support

  11. Review related documentation:

  12. CLI Configuration File
  13. Duplicate Detection
  14. Cluster Ingest

  15. General CLI Troubleshooting

  16. Contact support:

  17. Include CLI logs and error messages
  18. Describe the command you ran and the data you're importing
  19. Flywheel Support