Troubleshooting

Solutions for common GetWebP CLI issues, organized by category. Each entry follows a Problem / Cause / Solution pattern so you can find your fix fast.

See also: Getting Started | Commands Reference | Exit Codes

Table of Contents #

Installation Issues
License & Activation Issues
Conversion Issues
Network Issues
Debug Mode
Known Issues
Still Stuck?

Installation Issues #

"command not found: getwebp"#

Cause: The binary is not on your system PATH, or it was not renamed correctly.

Solution:

# macOS / Linux: move to a directory on PATH
sudo mv getwebp-macos-arm64 /usr/local/bin/getwebp
chmod +x /usr/local/bin/getwebp
 
# Verify
getwebp --version

On Windows, rename the file to getwebp.exe and either place it in C:\Windows\System32 or add its folder to the system PATH environment variable.

"permission denied" when running getwebp (macOS / Linux)#

Cause: The binary does not have execute permission.

Solution:

chmod +x /usr/local/bin/getwebp

macOS Gatekeeper blocks the binary ("cannot be opened because the developer cannot be verified")#

Cause: macOS quarantines unsigned binaries downloaded from the internet.

Solution:

xattr -cr /usr/local/bin/getwebp

Then run getwebp --version again. If macOS still blocks it, go to System Settings > Privacy & Security and click Allow Anyway next to the GetWebP message.

Node.js version incompatibility (building from source)#

Cause: If you are building GetWebP from source rather than using the prebuilt binary, the project requires a minimum Node.js version that supports ES modules and fetch.

Solution:

Use Node.js 18.x or later (20.x LTS recommended).
Run node --version to check your current version.
Use a version manager like nvm or fnm to switch versions.

Most users should download the prebuilt binary from getwebp.com/download instead of building from source.

License & Activation Issues #

"Activation failed: Invalid license key"#

Cause: The license key was mistyped, has already been refunded, or has been revoked.

Solution:

Double-check the key from your purchase confirmation email. Keys are in the format XXXX-XXXX-XXXX-XXXX.
Copy-paste the key to avoid typos:
```
getwebp auth XXXX-XXXX-XXXX-XXXX
```
If the key was purchased recently, wait a few minutes for payment processing to complete.
Check your license status on the dashboard.

Exit code: 1 (Generic Error)

"Activation failed" due to device limit reached #

Cause: Your license key has been activated on the maximum number of devices. Starter allows 3 devices; Pro allows 5.

Solution:

Check current device bindings:
```
getwebp status
```
The output shows Devices: X / Y used.
Free up a slot by logging out from a device you no longer use:
```
getwebp logout
```
Or unbind a device via the online dashboard.
Then activate on the new device:
```
getwebp auth XXXX-XXXX-XXXX-XXXX
```

License shows as expired #

Cause: The license subscription has expired or was not renewed.

Solution:

Verify expiry with:
```
getwebp status
```
Renew your license at getwebp.com/pricing.
After renewal, re-activate:
```
getwebp auth XXXX-XXXX-XXXX-XXXX
```

Exit code: 3 (Auth Error)

"Token is invalid or expired" after reinstalling or changing hardware #

Cause: GetWebP ties the license to a device fingerprint derived from the machine's hardware ID. Reinstalling the OS, changing hardware, or copying the config file to another machine invalidates the stored token.

Solution:

Re-activate the license on the current device:
```
getwebp auth XXXX-XXXX-XXXX-XXXX
```
If you are out of device slots, free one via getwebp logout on an old device or through the dashboard.

Logout fails: "Cannot reach server"#

Cause: The logout command requires network access to unbind the device server-side. Without connectivity, local credentials are not cleared.

Solution:

Check your internet connection and try again:
```
getwebp logout
```
If network access is unavailable, unbind the device through the online dashboard instead.

Exit code: 4 (Network Error)

Logout fails: "No active license found on this device"#

Cause: No license is currently activated on this device, or the token was already cleared.

Solution: No action needed. The device is already on the Free plan. Verify with:

getwebp status

Conversion Issues #

"Error: Please specify an input path"#

Cause: The convert command was run without specifying a file or directory.

Solution:

# Provide a path as a positional argument
getwebp convert ./images
 
# Or use the -i flag
getwebp convert -i ./images

Exit code: 1 | JSON error code: missing_input

"Path not found: ..."#

Cause: The specified input file or directory does not exist, or there is a typo in the path.

Solution:

Verify the path exists:
```
ls -la ./images
```
Use an absolute path if relative paths are causing confusion:
```
getwebp convert /Users/you/project/images
```

No files found in directory (0 files processed)#

Cause: The directory contains no supported image files (JPG, JPEG, PNG, BMP, WebP), or images are in subdirectories but -r was not used.

Solution:

Confirm the directory contains supported files:
```
ls ./images/*.{jpg,jpeg,png,bmp,webp}
```
To process subdirectories, add the -r flag:
```
getwebp convert ./images -r
```

Supported formats: JPG, JPEG, PNG, BMP, WebP (re-encoded).

"Decode failed" on a specific file #

Cause: The image file is corrupt, truncated, or not a valid image despite having an image file extension.

Solution:

Open the file in an image viewer to confirm it is valid.
Try re-downloading or re-exporting the image from its source.

Use --json to identify which specific files failed:

getwebp convert ./images --json 2>/dev/null | jq '.results[] | select(.status == "error")'

Convert the remaining files by moving the corrupt file out of the directory.

Exit code: 2 (Partial Failure) if other files succeeded.

"Write failed" or permission errors on output #

Cause: The output directory is read-only, does not exist and cannot be created, or disk space is full.

Solution:

Verify the output directory is writable:

# Test write access
touch ./output/test && rm ./output/test

Create the output directory first if needed (GetWebP does create it automatically, but parent directories must exist):
```
mkdir -p ./output
```
Check available disk space:
```
df -h .
```
On macOS, ensure Terminal or your shell has Full Disk Access if converting files in protected locations (Desktop, Documents, Downloads).

"Output path too long for Windows" error #

Cause: Windows has a default maximum path length of 260 characters. Deeply nested directories or long filenames can exceed this limit.

Solution:

Use a shorter output path:

getwebp convert ./deep/nested/images -o C:\out

Or enable long paths in Windows by setting LongPathsEnabled to 1 in the registry at:
```
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem
```

Conversion is slow (Free plan)#

Cause: The Free plan enforces a 3-second delay between each file and limits processing to 10 files per run. Parallel processing is disabled.

Solution:

Upgrade to Starter or Pro at getwebp.com/pricing for instant processing with parallel workers.
After purchase:
```
getwebp auth XXXX-XXXX-XXXX-XXXX
```

"Conflict: ... all map to the same .webp"#

Cause: Multiple source files in the same directory share a base name (e.g., photo.png and photo.jpg). Both would produce photo.webp, so only the last one processed survives.

Solution:

Rename one of the conflicting source files before converting.

Or convert them into separate output directories:

getwebp convert photo.png -o ./out-png
getwebp convert photo.jpg -o ./out-jpg

Partial failure: some files succeeded, others failed #

Cause: Individual files may fail due to corruption, permission issues, or disk space while others convert normally.

Solution:

Run with --json to see per-file results:
```
getwebp convert ./images --json
```
Check the results array for entries with "status": "error" and read their error message.
Fix or remove the problematic files and re-run with --skip-existing to avoid re-converting successful files:
```
getwebp convert ./images --skip-existing
```

Exit code: 2 (Partial Failure)

Network Issues #

"Cannot reach server" during activation or logout #

Cause: The CLI cannot connect to api.getwebp.com. This can be caused by no internet connection, a firewall, a corporate proxy, or DNS issues.

Solution:

Test basic connectivity:
```
curl -I https://api.getwebp.com
```
If behind a corporate proxy, configure your system's HTTP proxy settings. GetWebP uses the system fetch implementation, which respects HTTPS_PROXY and HTTP_PROXY environment variables:
```
export HTTPS_PROXY=http://proxy.corp.example:8080
getwebp auth XXXX-XXXX-XXXX-XXXX
```
If DNS is the issue, try using a public DNS resolver (e.g., 1.1.1.1 or 8.8.8.8).
Wait and retry. The API has a 5-second timeout. Transient failures are retryable.

Exit code: 4 (Network Error) | JSON error code: network_unreachable

Status shows "cached" data #

Cause: getwebp status could not reach the server, so it displayed the last known state from local cache.

Solution: This is expected behavior when offline. The cached status is still valid for conversions (the license JWT is verified locally). To refresh, restore network access and run:

getwebp status

Debug Mode #

When reporting a bug or diagnosing an unexpected issue, use --debug to see detailed internal logs.

Enabling debug output #

getwebp convert ./images --debug

The --debug flag implies --verbose. Debug messages are prefixed with [debug] and written to stderr, so they do not interfere with --json output on stdout.

What debug output shows #

File scanning: Which files were discovered and how many matched.
Processing pipeline: Per-file start/finish with status (success, error, skipped).
License check: Token verification results and heartbeat activity.
Configuration: Config file location and machine ID resolution.

Example debug output #

[debug] processImages ./images { plan: 'starter', concurrency: 7, recursive: true, dryRun: false, skipExisting: false }
[debug] collected 42 files
[debug] converting ./images/photo-01.jpg
[debug] done ./images/photo-01.jpg success
[debug] converting ./images/photo-02.png
[debug] done ./images/photo-02.png success

Combining debug with JSON output #

To capture machine-readable results while still seeing debug logs:

getwebp convert ./images --json --debug 2>debug.log >results.json

results.json contains structured JSON output.
debug.log contains [debug] messages and warnings.

Known Issues #

Symlinks are skipped #

GetWebP skips symbolic links for safety. If your image directory contains symlinks, the linked files will not be processed.

Workaround: Copy or move the actual files into the target directory, or point GetWebP at the real file paths.

WebP-to-WebP self-overwrite is skipped #

When converting a .webp file without specifying a separate output directory, the input and output paths are identical. GetWebP detects this and skips the file to prevent data loss.

Workaround: Use -o to specify a different output directory:

getwebp convert ./images -o ./images-reencoded

Config file cannot be decrypted after hostname change #

The config file at ~/.config/getwebp-nodejs/config.json is encrypted using the machine's hardware ID. If the hardware ID changes (e.g., hostname change on a system where the hardware ID could not be read), the stored token becomes unreadable.

Workaround: Re-activate the license:

getwebp auth XXXX-XXXX-XXXX-XXXX

You can override the config directory with the GETWEBP_CONFIG_DIR environment variable if needed.

getwebp convert ./images --debug 2>debug.log

Check your exit code to narrow the category:
```
echo $?
```
See Exit Codes for what each code means.
Visit the dashboard to check your license and device status.
Contact support at getwebp.com with:
- Your CLI version (getwebp --version)
- Your OS and architecture
- The debug log output
- The exit code

See also: Getting Started | Commands Reference | Exit Codes | Configuration (coming soon)

Tài liệu tham khảo

Troubleshooting