Exit Codes
Every df-cli command returns an integer exit code. 0 means success; any other value indicates an error or special status. These codes are returned as the process exit code and can be checked in scripts and other automation.
General
| Code |
Name |
Description |
| -1 |
DF_SHOULD_REBUILD |
Returned by build --check when recompilation is needed. This is not an error — it signals that source files have changed since the last build. |
| 0 |
DF_OK |
The command completed successfully. |
| 1 |
DF_FATAL_ERROR |
An unrecoverable internal error occurred. This typically indicates a bug or a corrupt installation. |
| 2 |
DF_GIT_NOT_AVAILABLE |
A Git dependency was declared but Git is not installed or not on the system PATH. Install Git and ensure it is accessible from the command line. |
Filesystem
| Code |
Name |
Description |
| 3 |
DF_FILE_PERMISSION_ERROR |
A file or directory could not be read or written due to insufficient permissions. On Windows, check that the file is not read-only or locked by another process. |
| 4 |
DF_FILE_DOES_NOT_EXIST |
A required file was not found on disk. This can occur when a workspace references a file that has been moved or deleted (e.g. an icon, license file, or source file). |
| 5 |
DF_FILE_FAILED_TO_EXTRACT |
A package archive (ZIP) could not be extracted. The archive may be corrupt, incomplete, or in an unsupported format. Re-download or re-pack the package. |
| 6 |
DF_FILE_FAILED_TO_HASH |
File hashing failed during install-file conflict detection. This can happen if a file is locked or unreadable at the moment df-cli tries to compute its hash. |
Workspace
| Code |
Name |
Description |
| 7 |
DF_WORKSPACE_NOT_OPEN |
An operation was attempted on a workspace that has not been loaded. This is typically an internal sequencing error. |
| 8 |
DF_WORKSPACE_FILE_NO_EXISTS |
The .sws workspace file specified on the command line does not exist. Check the path and filename. |
| 9 |
DF_WORKSPACE_ALREADY_EXISTS |
The create command was run but a workspace with that name already exists in the target directory. Choose a different name or output directory. |
| 10 |
DF_WORKSPACE_CREATION_FAILURE |
Workspace creation failed. This can occur if the workspace template is missing from the DataFlex installation, or the target directory is not writable. |
| 11 |
DF_WORKSPACE_WRITE_FAILURE |
The workspace .sws file could not be written. Check that the file is not read-only and that the directory has sufficient disk space. |
Dependency
| Code |
Name |
Description |
| 12 |
DF_DEPENDENCY_REQUIRED |
A required dependency is declared in the workspace but could not be resolved from any source (repository, Git, or local path). Verify the dependency name and source. |
| 13 |
DF_DEPENDENCY_NOT_INSTALLED |
An operation (e.g. uninstall, upgrade) references a dependency that is not currently installed in the workspace. Run df-cli config to inspect installed dependencies. |
| 14 |
DF_DEPENDENCY_INVALID |
A dependency definition in the .sws file is malformed. Check the dependencies array for syntax errors — each entry must be a string or an object with a source field. See the Workspace Configuration Format. |
| 15 |
DF_DEPENDENCY_INCOMPATIBLE |
Two or more packages in the dependency tree require the same package at incompatible version constraints. For example, one requires ~1.2.0 and another requires ^2.0.0. Align the version constraints or update the conflicting packages. |
| 16 |
DF_DEPENDENCY_MISSING_CONFIG |
A dependency was found on disk (in dfpkg/) but its workspace configuration file is missing or unreadable. Try uninstalling and reinstalling the dependency, or use config --repair. |
| 17 |
DF_DEPENDENCY_FETCH_ERROR |
Failed to fetch a dependency from its source. For repository packages, check your network connection and authentication (df-cli login). For Git dependencies, verify the URL is correct and accessible. |
| 18 |
DF_DEPENDENCY_FAILED_TO_FETCH_LATEST_VERSION |
The package repository could not determine the latest version that satisfies the version constraint. This may indicate that no published version matches the constraint, or a network issue. |
| 19 |
DF_DEPENDENCY_FAILED_TO_INSTALL_FILES |
A dependency's install files could not be copied into the workspace. This can occur due to permission errors or file conflicts. Resolve the conflicting files and rerun the install or upgrade operation. |
| 20 |
DF_DEPENDENCIES_UP_TO_DATE |
Returned by package update when all dependencies are already at their latest compatible versions. Not an error — no action is needed. |
Configuration
| Code |
Name |
Description |
| 21 |
DF_CONFIG_PARSE_ERROR |
The .sws file could not be parsed. It is likely not valid JSON. Check for syntax errors (missing commas, unquoted keys, trailing commas). If the file is in legacy INI format, run df-cli convert first. |
| 22 |
DF_CONFIG_INVALID |
The .sws file was parsed but contains invalid values (e.g. wrong types, missing required fields). Run df-cli config to see which fields are invalid. See the Workspace Configuration Format for the expected schema. |
CLI
| Code |
Name |
Description |
| 23 |
DF_CLI_ARGUMENT_ERROR |
Invalid or missing command-line arguments. Run df-cli --help or df-cli <command> --help to see the expected usage. |
Cache
These errors relate to the local package cache in the dfpkg/ directory.
| Code |
Name |
Description |
| 24 |
DF_CACHE_MISSING |
The package cache directory for a dependency does not exist. The package may have been partially uninstalled or the dfpkg/ folder was manually modified. Reinstall the affected package. |
| 25 |
DF_CACHE_INVALID |
The package cache configuration is corrupt or unreadable. Reinstall the affected package to rebuild the cache. |
| 26 |
DF_CACHE_MISMATCH |
Files in the package cache do not match the expected state (hash mismatch). This can happen if files were manually edited inside dfpkg/. Use config --repair to diagnose and fix, or reinstall the package. |
| 27 |
DF_CACHE_CREATION_FAILURE |
Failed to create the package cache directory or write cache files. Check disk space and directory permissions. |
API
These errors occur when communicating with the package repository at packages.dataflex.dev.
| Code |
Name |
Description |
| 28 |
DF_API_ERROR |
The package repository API returned an error. This is a catch-all for server-side failures including 4xx and 5xx HTTP responses. The error message will include details from the API response. Common causes: package not registered (409 on push), permission denied (403), or server outage. |
| 29 |
DF_API_REQUIRE_LOGIN |
Authentication is required for this operation. Run df-cli login to authenticate with the repository endpoint. For non-interactive use, --access-token and --refresh-token can be supplied directly. |
| 30 |
DF_API_TOKEN_EXPIRED |
The stored access token has expired. Run df-cli login again to obtain a new token. |
Quick Reference
| Code |
Name |
| -1 |
DF_SHOULD_REBUILD |
| 0 |
DF_OK |
| 1 |
DF_FATAL_ERROR |
| 2 |
DF_GIT_NOT_AVAILABLE |
| 3 |
DF_FILE_PERMISSION_ERROR |
| 4 |
DF_FILE_DOES_NOT_EXIST |
| 5 |
DF_FILE_FAILED_TO_EXTRACT |
| 6 |
DF_FILE_FAILED_TO_HASH |
| 7 |
DF_WORKSPACE_NOT_OPEN |
| 8 |
DF_WORKSPACE_FILE_NO_EXISTS |
| 9 |
DF_WORKSPACE_ALREADY_EXISTS |
| 10 |
DF_WORKSPACE_CREATION_FAILURE |
| 11 |
DF_WORKSPACE_WRITE_FAILURE |
| 12 |
DF_DEPENDENCY_REQUIRED |
| 13 |
DF_DEPENDENCY_NOT_INSTALLED |
| 14 |
DF_DEPENDENCY_INVALID |
| 15 |
DF_DEPENDENCY_INCOMPATIBLE |
| 16 |
DF_DEPENDENCY_MISSING_CONFIG |
| 17 |
DF_DEPENDENCY_FETCH_ERROR |
| 18 |
DF_DEPENDENCY_FAILED_TO_FETCH_LATEST_VERSION |
| 19 |
DF_DEPENDENCY_FAILED_TO_INSTALL_FILES |
| 20 |
DF_DEPENDENCIES_UP_TO_DATE |
| 21 |
DF_CONFIG_PARSE_ERROR |
| 22 |
DF_CONFIG_INVALID |
| 23 |
DF_CLI_ARGUMENT_ERROR |
| 24 |
DF_CACHE_MISSING |
| 25 |
DF_CACHE_INVALID |
| 26 |
DF_CACHE_MISMATCH |
| 27 |
DF_CACHE_CREATION_FAILURE |
| 28 |
DF_API_ERROR |
| 29 |
DF_API_REQUIRE_LOGIN |
| 30 |
DF_API_TOKEN_EXPIRED |