jruby/jruby · error · Encoding::CompatibilityError

path name must be ASCII-compatible ({enc}): {str}

Error message

path name must be ASCII-compatible ({enc}): {str}

What it means

Error "path name must be ASCII-compatible ({enc}): {str}" thrown in jruby/jruby.

Source

Thrown at core/src/main/java/org/jruby/RubyFile.java:1455

        return getPathCheckConvert(context, getPathCheckToString(context, path));
    }

    // CRuby rb_get_path_check_convert
    private static RubyString getPathCheckConvert(ThreadContext context, RubyString path) {
        path = filePathConvert(context, path);

        checkPathEncoding(context, path);

        checkEmbeddedNulls(context, path);

        return path.strDup(context.runtime);
    }

    // CRuby: check_path_encoding
    private static Encoding checkPathEncoding(ThreadContext context, RubyString str) {
        Encoding enc = str.getEncoding();
        if (!enc.isAsciiCompatible()) {
            throw Error.encodingCompatibilityError(context, "path name must be ASCII-compatible (" + enc + "): " + str);
        }
        return enc;
    }

    // CRuby: rb_get_path_check_to_string
    private static RubyString getPathCheckToString(ThreadContext context, IRubyObject path) {
        if (path instanceof RubyString) return (RubyString) path;

        FileSites sites = sites(context);
        if (sites.respond_to_to_path.respondsTo(context, path, path, true)) path = sites.to_path.call(context, path, path);

        return path.convertToString();
    }

    // FIXME: MRI skips this logic on windows?  Does not make sense to me why so I left it in.
    // mri: file_path_convert
    protected static RubyString filePathConvert(ThreadContext context, RubyString path) {
        checkEmbeddedNulls(context, path);

View on GitHub (pinned to fb650c13e0)

Solutions

1. The file path string uses an encoding that is not ASCII-compatible (e.g. UTF-16/UTF-32). Convert the path to an ASCII-compatible encoding such as UTF-8 before passing it to the file API.

When it happens

Trigger: Thrown at core/src/main/java/org/jruby/RubyFile.java:1455 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of jruby/jruby@fb650c13e0 (2026-08-23). Data as JSON: /api/errors/4ee031e9a69ff0d2. Report an issue: GitHub.