appsmithorg/appsmith · error · AppsmithPluginException

PE-PLG-5003

PE-PLG-5003

Error message

Provided file format is incompatible, please upgrade your instance to resolve this conflict.

What it means

Thrown by FileUtilsCEImpl.fetchGitResourceMap after reading repo metadata. It reads the metadata.json, extracts fileFormatVersion via fileOperations.getFileFormatVersion(metadata), and calls isFileFormatCompatible(version), which returns true only when savedFileFormat <= CommonConstants.fileFormatVersion (the running server's format). If the repo was written by a NEWER Appsmith than the one reading it, the check fails and AppsmithPluginException(INCOMPATIBLE_FILE_FORMAT, PE-PLG-5003) is thrown with the message 'Provided file format is incompatible, please upgrade your instance to resolve this conflict.'

Source

Thrown at app/server/appsmith-git/src/main/java/com/appsmith/git/files/FileUtilsCEImpl.java:704

                        directoryPath.resolve(resourceName).resolve(CommonConstants.METADATA + JSON_EXTENSION));
                actionCollectionBodyMap.put(resourceName + keySuffix, body);
                resource.put(resourceName + keySuffix, file);
            }
        }
        return resource;
    }

    private Object readPageMetadata(Path directoryPath) {
        return readFileValidated(directoryPath.resolve(directoryPath.toFile().getName() + JSON_EXTENSION));
    }

    protected GitResourceMap fetchGitResourceMap(Path baseRepoPath) throws IOException {
        // Extract application metadata from the json
        Object metadata = readFileValidated(baseRepoPath.resolve(CommonConstants.METADATA + JSON_EXTENSION));
        Integer fileFormatVersion = fileOperations.getFileFormatVersion(metadata);
        // Check if fileFormat of the saved files in repo is compatible
        if (!isFileFormatCompatible(fileFormatVersion)) {
            throw new AppsmithPluginException(AppsmithPluginError.INCOMPATIBLE_FILE_FORMAT);
        }

        GitResourceMap gitResourceMap = new GitResourceMap();
        Map<GitResourceIdentity, Object> resourceMap = gitResourceMap.getGitResourceMap();

        Set<String> filesInRepo = getExistingFilesInRepo(baseRepoPath);
        // Remove all files that need not be fetched to the git resource map
        // i.e. ->  README.md
        filesInRepo.remove(README_FILE_NAME);

        filesInRepo.parallelStream()
                .filter(path -> !Files.isDirectory(baseRepoPath.resolve(path)))
                .forEach(filePath -> {
                    Tuple2<GitResourceIdentity, Object> identity = getGitResourceIdentity(baseRepoPath, filePath);

                    resourceMap.put(identity.getT1(), identity.getT2());
                });

View on GitHub (pinned to 8cd9021c24)

Solutions

1. Upgrade the Appsmith instance to a version whose fileFormatVersion is >= the value in the repo's metadata.json (the message tells the user to upgrade).
2. Check the repo's metadata.json for the fileFormatVersion field and compare to the running server's supported version.
3. If upgrading is not possible, re-export the app from a server at or below the target version, or recreate the app on the older instance.
4. Keep all environments that share a git remote on the same (or newer) Appsmith version to avoid forward-incompatible reads.

Example fix

// before
# repo metadata.json: "fileFormatVersion": 3
# running server supports: up to 2  -> INCOMPATIBLE

// after
# upgrade server to a release supporting fileFormatVersion >= 3
# (then re-run connect/pull/import)

# Pre-flight: compare repo fileFormatVersion to the running server's max.
repo_version="$(jq -r '.fileFormatVersion' repo/metadata.json)"
server_max="$(get_supported_fileFormatVersion)"
[ "$repo_version" -le "$server_max" ] \
  || echo "reject: repo format $repo_version > server max $server_max"

// Java-side check mirroring isFileFormatCompatible
boolean isCompatible(Integer saved, int serverMax) {
  return saved != null && saved <= serverMax;
}

try {
  fileUtils.fetchGitResourceMap(baseRepoPath);
} catch (AppsmithPluginException e) {
  if (e.getCode() == AppsmithPluginError.INCOMPATIBLE_FILE_FORMAT) {
    log.error("Repo fileFormatVersion too new; upgrade this instance.");
  }
  throw e;
}

When it happens

Trigger: Connecting to / pulling / importing a git repository whose metadata.json carries a fileFormatVersion higher than the current server supports: a repo exported by a newer Appsmith release being opened by an older one; downgrading the Appsmith server below the version that wrote the repo; cloning an app between environments with different versions.

Common situations: Downgrading Appsmith after apps were saved in a newer format; pulling a repo authored on a cloud/newer instance into a self-hosted older instance; version mismatch between two self-hosted environments sharing a git remote.

Related errors

• PE-PLG-5000
• Error while rebasing the branch, {}
• PE-DSE-5000
• PE-DSE-5003
• PE-JSN-4000

AI-assisted analysis of appsmithorg/appsmith@8cd9021c24 (2026-08-12). Data as JSON: /api/errors/767f315d8a6b3a77. Report an issue: GitHub.