Repository navigation
Troubleshooting
Home / Troubleshooting
Something not working as expected? Find your problem below and try the checks in order. After each change, check whether it helped before changing something else. Use the small-file transfer test to separate a basic FTP problem from an integration problem.
On this page
- Server not discovered
- Connection fails
- Browser does not load
- Upload controls or missing files
- Unreadable saved content
- Overwrites or invalid filenames
- URLs and downloads
- Unexpected starting folder
Likely cause: the server is not announcing its FTP service on your network, or Homey cannot find that announcement.
- Confirm the FTP service is running and accessible on the intended network.
- For Synology, check whether Bonjour/mDNS is enabled in DSM's File Services.
- If discovery remains unavailable, add a custom FTP Connection and enter the server's hostname/IP address, port, username, and password.
Verify: open the paired device's Repair view and check that a directory listing loads. An empty directory is a valid listing; pairing alone does not prove that the connection works.
Likely causes: an incorrect address, port, login details, connection type, or certificate configuration.
- Check the hostname/IP address and port. Enter a hostname or IP, not a full URL or a folder path.
- Verify the username and password against the FTP server. A successful login from your computer helps confirm the login details, but Homey must also be able to reach the server from its own network.
- Check whether the service expects plain FTP or FTPS, then set Secure accordingly. Secure means FTPS, not SSH-based SFTP.
- For FTPS, check that the hostname matches a valid server certificate. Only consider Allow incorrect certificate for a trusted server when certificate validation cannot be resolved; it disables validation.
An SSH/SFTP-only service on port 22 will not work with this app. Ask the
provider whether FTPS is available instead of disabling encryption as a
routine internet-connection workaround. See the
community explanation.
Verify: reopen Repair and confirm the listing loads. Then upload and download a small test file; listing permission and write permission can differ.
Likely causes: Better Logic Library is not available, or the FTP connection has failed.
- Confirm Better Logic Library is installed and running on Homey.
- Close and reopen the repair view after enabling it.
- If the interface appears but cannot list files, follow connection checks.
Verify: the browser controls and an FTP directory listing are visible.
Expected behavior: selecting files starts the upload automatically. There is no separate confirmation button.
- Open the folder context menu to choose Upload file(s), including in an empty folder.
- Select a small test file and wait for the loading overlay to finish.
- Refresh the directory. If the file is missing, verify that the account can write to that folder and review any error shown.
Verify: the uploaded file appears and its downloaded content matches. Use the first transfer test.
Likely causes: plain text supplied to a base64 card, double encoding, or a filename extension that does not match the content.
- Confirm Save File from base64 receives raw base64, not a plain sensor
value or a
data:...;base64,URL. - If the producing app already exports base64, pass that token directly without encoding it again.
- For text, encode the UTF-8 bytes. For binary data, preserve the bytes before encoding; treating them as a text response can corrupt the file.
- Choose a matching filename extension. Renaming a file does not convert it.
Verify: run the minimal text example:
MjA= saved as temperature.txt must download as exactly 20.
Then try your own file in the app you want to use to open it.
For an HTTP 413 error, reduce the export size and identify the action or
request that fails. Browser uploads are split into parts; this does not
guarantee identical limits for a large Flow token from another app.
Likely causes: a fixed destination name, incomplete filename, or date punctuation rejected by the server's filesystem.
- Supply the full destination filename, including the appropriate extension.
- Use a varying filename when retaining successive files. Fixed names deliberately replace the previous file.
- Choose a filesystem-safe date pattern or timestamp; some formats contain slashes or colons. See BLL coding.
- If a later card retrieves the saved file, reuse the same resolved filename rather than evaluating a new timestamp.
Verify: run two saves at different times, then check that two distinct files exist and both open correctly when using the archive pattern.
Likely causes: the device opening the link cannot reach Homey, the temporary file is no longer available, or the receiving app cannot use that link or format.
- Identify the URL's source. For repair downloads, select a device URL mode reachable from the device opening the link. For Get file URL, use its URL or Cloud URL token; the device mode does not select these outputs.
- Away from home, choose Cloud (SSL) for repair downloads or try Cloud URL from the Flow card. If repair icons also fail remotely, choose Cloud (SSL) for their setting.
- Advanced network check: for local HTTPS, check that the device can find and connect to Homey using its local network name. Your router's DNS-rebinding protection may block this connection. Follow Homey's local-connection guidance rather than turning that protection off globally.
- Generate a fresh URL or image token and use it promptly. For repair downloads and FTP-file images, increase Download Time (Seconds) if needed. For the app-level HTTP image card, adjust Available duration instead.
Verify: open the fresh link on the network used by your speaker, device, or receiving app, then test it there. A phone opening the file does not prove that a speaker or another device can reach the same address or decode the format.
Cause: the FTP server determines the account's starting directory. The current app does not apply Work (Default) Directory.
- Check the FTP account's home directory and folder permissions on the server.
- Configure the intended starting directory there, or navigate to the folder in the browser and select it explicitly in Flow cards.
Verify: reopen Repair and confirm that the expected folders are accessible. Do not expect changing the unused device setting to alter them.
Support development - If FTP Client is useful to you, you can support its
continued development through GitHub Sponsors,
Patreon,
PayPal, or
bunq.
Thank you!