flowable/flowable-engine · error · FlowableException

Couldn't write file

Error message

Couldn't write file ${filePath}

What it means

Flowable wraps any exception thrown while writing a string to a file at the given path into a FlowableException with this message. It is thrown by IoUtil.writeStringToFile when opening, writing to, or flushing the FileOutputStream fails, and the original exception is preserved as the cause.

Solutions

1. Read the 'cause' field of the FlowableException to see the underlying IOException (NoSuchFileException, AccessDeniedException, etc.).
2. Create all parent directories before writing (Files.createDirectories on the parent path).
3. Verify the filePath is a valid file path, not a directory, and is writable by the process user.
4. Check disk space and filesystem permissions.
5. If only the output location is wrong, fix the configured output directory.

Example fix

// before
IoUtil.writeStringToFile("target/reports/diagram.svg", svg);
// after
Files.createDirectories(Paths.get("target/reports"));
IoUtil.writeStringToFile("target/reports/diagram.svg", svg);

Path path = Paths.get(filePath);
if (!Files.exists(path.getParent())) Files.createDirectories(path.getParent());
if (Files.isDirectory(path)) throw new IllegalStateException("Path is a directory: " + filePath);
if (!Files.isWritable(path.getParent())) throw new IllegalStateException("Not writable: " + path.getParent());

When it happens

Trigger: Calling IoUtil.writeStringToFile(filePath, content) when the target directory does not exist, the path is a directory, the file cannot be opened (permissions, invalid path), or an I/O error occurs mid-write/flush.

Common situations: Generating process diagram/report files into a directory that was never created; read-only filesystems or containers; invalid paths from configuration (e.g. wrong resource folder); disk full.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

• couldn't open resource stream: " + e.getMessage()
• couldn't open resource stream
• Couldn't write file
• Failed to read resource
• problem reading zip input stream

AI-assisted analysis of flowable/flowable-engine@d6d39ce1c6 (2026-09-11). Data as JSON: /api/errors/08a41003ddc827f5. Report an issue: GitHub.

Appendix: source

Thrown at modules/flowable-engine-common/src/main/java/org/flowable/common/engine/impl/util/IoUtil.java:80

    }

    public static File getFile(String filePath) {
        URL url = IoUtil.class.getClassLoader().getResource(filePath);
        try {
            return new File(url.toURI());
        } catch (Exception e) {
            throw new FlowableException("Couldn't get file " + filePath + ": " + e.getMessage());
        }
    }

    public static void writeStringToFile(String content, String filePath) {
        BufferedOutputStream outputStream = null;
        try {
            outputStream = new BufferedOutputStream(new FileOutputStream(getFile(filePath)));
            outputStream.write(content.getBytes());
            outputStream.flush();
        } catch (Exception e) {
            throw new FlowableException("Couldn't write file " + filePath, e);
        } finally {
            IoUtil.closeSilently(outputStream);
        }
    }

    /**
     * Closes the given stream. The same as calling {@link InputStream#close()}, but errors while closing are silently ignored.
     */
    public static void closeSilently(InputStream inputStream) {
        try {
            if (inputStream != null) {
                inputStream.close();
            }
        } catch (IOException ignore) {
            // Exception is silently ignored
        }
    }

View on GitHub (pinned to d6d39ce1c6)