apache/pulsar · error · FileNotFoundException

Schema file %s is not found. Relative path %s is resolved to

Error message

Schema file %s is not found. Relative path %s is resolved to %s. Try to use absolute path if the relative one resolved wrongly.

What it means

`pulsar-admin schemas upload` reads the schema definition from a file given by --schema-file. If the resolved path does not exist, a FileNotFoundException is thrown with an extended message showing how a relative path was resolved (against the process working directory) and advising an absolute path.

Source

Thrown at pulsar-client-tools/src/main/java/org/apache/pulsar/admin/cli/CmdSchemas.java:132

        private String topicName;

        @Option(names = { "-f", "--filename" }, description = "filename", required = true)
        private String schemaFileName;

        @Override
        void run() throws Exception {
            String topic = validateTopicName(topicName);
            Path schemaPath = Path.of(schemaFileName);
            File schemaFile = schemaPath.toFile();
            if (!schemaFile.exists()) {
                final StringBuilder sb = new StringBuilder();
                sb.append("Schema file ").append(schemaPath).append(" is not found.");
                if (!schemaPath.isAbsolute()) {
                    sb.append(" Relative path ").append(schemaPath)
                            .append(" is resolved to ").append(schemaPath.toAbsolutePath())
                            .append(". Try to use absolute path if the relative one resolved wrongly.");
                }
                throw new FileNotFoundException(sb.toString());
            }
            PostSchemaPayload input = MAPPER.readValue(schemaFile, PostSchemaPayload.class);
            getAdmin().schemas().createSchema(topic, input);
        }
    }

    @Command(description = "Provide the schema via a topic")
    private class ExtractSchema extends CliCommand {
        @Parameters(description = "persistent://tenant/namespace/topic", arity = "1")
        private String topicName;

        @Option(names = { "-j", "--jar" }, description = "jar filepath", required = true)
        private String jarFilePath;

        @Option(names = { "-t", "--type" }, description = "type avro or json", required = true)
        private String type;

        @Option(names = { "-c", "--classname" }, description = "class name of pojo", required = true)

View on GitHub (pinned to 820761864e)

Solutions

Use an absolute path: --schema-file /etc/pulsar/schema/my-schema.json
Check the 'is resolved to' portion of the message to see the directory the CLI is actually running from
Verify the file exists (ls) and is readable by the user running pulsar-admin
Fix the working directory of scripts/services that invoke the CLI

Example fix

// before
pulsar-admin schemas upload --topic t --schema-file schema.json
// after
pulsar-admin schemas upload --topic t --schema-file /opt/schemas/schema.json

Defensive patterns

Strategy: validation

Validate before calling

java.nio.file.Path p = java.nio.file.Paths.get(schemaFile);
if (!java.nio.file.Files.isRegularFile(p)) {
    throw new IllegalArgumentException("Schema file not found: " + p.toAbsolutePath());
}

Try / catch

try {
    admin.schemas().createSchema(topic, payload);
} catch (java.io.FileNotFoundException e) {
    // resolve schema file against the correct directory or switch to absolute path
}

Prevention

Always use absolute paths for --schema-file in scripts and services
Log/verify the process working directory in cron, systemd, and CI runners
Mount schema files into containers and check readability before upload

When it happens

Trigger: Running `pulsar-admin schemas upload` with a --schema-file path that does not exist, or a relative path resolved against a different working directory than the user expected (e.g. running from systemd, another cwd, or a wrapper script).

Common situations: Typos in filename; running the CLI from a different directory than intended in cron/systemd/CI; the schema file was deleted or not mounted in a container; assuming resolution relative to the topic or config file rather than cwd.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

AI-assisted analysis of apache/pulsar@820761864e (2026-09-06). Data as JSON: /api/errors/b5771b84086f178b. Report an issue: GitHub.