Troubleshooting
Reproduce with one file, one destination, and one upload interface. Separate upload delivery, result saving, and URL access failures before changing settings.
Upload failures
| Symptom | First check |
|---|---|
| First upload fails | Enter your credentials and select the destination |
| 401 / 403 | Token, account permissions, expiration, and access policy |
| Timeout or connection error | Endpoint, proxy, DNS, and service reachability |
| One named configuration fails | Configuration name, provider ID, and path |
| A batch fails but one file works | Rate limits, file size, and queue interval |
| Secondary results are missing | Test both destinations separately and inspect secondary errors |
Temporarily disable the processing or custom scripts relevant to the problem, verify a small raw upload, then restore one setting at a time.
Upload succeeds but the image is inaccessible
Check whether the object exists on the provider. If it does, inspect the generated URL instead of uploading repeatedly.
- Are the API endpoint and public domain confused?
- Is a bucket or directory segment added twice?
- Is the object privately or publicly readable?
- Has a signed URL expired?
- Was a localhost preview URL copied?
- Are CDN caches, hotlink rules, or request headers involved?
Image processing
For a missing watermark, check the font or image path. For unexpected compression, check configuration scope. For conversion failures, check available platform encoders; preview support does not imply output encoding support.
Clipboard
Save the image to a file and upload it first. If that works, check whether the clipboard contains image data, an absolute path, a file:// URL, or ordinary text. Linux and remote sessions can have desktop environment limitations.
Editors and servers
- Test an upload inside PicList.
- Check the correct port through /heartbeat.
- Verify the editor's full executable path or HTTP address.
- Send multipart file content remotely, not client-local paths.
- Core setup prompts, plugin configuration, and the TUI need an interactive terminal.
Desktop commands, standalone CLI, desktop API, and Core API have different requirements. See integrations.
Finalization failures and interrupted tasks
If the remote file exists and the error identifies finalization, recover the existing task first. API clients can use its finalizationId. Do not enable automatic source deletion or repeat the full queue without checking delivery state.
Report an issue
Include the version, operating system, provider ID, steps, and a sanitized error summary. Screenshots should exclude accounts, keys, QR codes, and private filenames.
Keep complete configurations, raw fullResult objects, and unchecked logs out of reports. Use PicList Issues for desktop problems and Core Issues for standalone Core.