{"record":{"id":"767f315d8a6b3a77","repo":"appsmithorg/appsmith","slug":"pe-plg-5003","errorCode":"PE-PLG-5003","errorMessage":"Provided file format is incompatible, please upgrade your instance to resolve this conflict.","messagePattern":"Provided file format is incompatible, please upgrade your instance to resolve this conflict\\.","errorType":"error_code","errorClass":"AppsmithPluginException","httpStatus":400,"severity":"error","filePath":"app/server/appsmith-git/src/main/java/com/appsmith/git/files/FileUtilsCEImpl.java","lineNumber":704,"sourceCode":"                        directoryPath.resolve(resourceName).resolve(CommonConstants.METADATA + JSON_EXTENSION));\n                actionCollectionBodyMap.put(resourceName + keySuffix, body);\n                resource.put(resourceName + keySuffix, file);\n            }\n        }\n        return resource;\n    }\n\n    private Object readPageMetadata(Path directoryPath) {\n        return readFileValidated(directoryPath.resolve(directoryPath.toFile().getName() + JSON_EXTENSION));\n    }\n\n    protected GitResourceMap fetchGitResourceMap(Path baseRepoPath) throws IOException {\n        // Extract application metadata from the json\n        Object metadata = readFileValidated(baseRepoPath.resolve(CommonConstants.METADATA + JSON_EXTENSION));\n        Integer fileFormatVersion = fileOperations.getFileFormatVersion(metadata);\n        // Check if fileFormat of the saved files in repo is compatible\n        if (!isFileFormatCompatible(fileFormatVersion)) {\n            throw new AppsmithPluginException(AppsmithPluginError.INCOMPATIBLE_FILE_FORMAT);\n        }\n\n        GitResourceMap gitResourceMap = new GitResourceMap();\n        Map<GitResourceIdentity, Object> resourceMap = gitResourceMap.getGitResourceMap();\n\n        Set<String> filesInRepo = getExistingFilesInRepo(baseRepoPath);\n        // Remove all files that need not be fetched to the git resource map\n        // i.e. ->  README.md\n        filesInRepo.remove(README_FILE_NAME);\n\n        filesInRepo.parallelStream()\n                .filter(path -> !Files.isDirectory(baseRepoPath.resolve(path)))\n                .forEach(filePath -> {\n                    Tuple2<GitResourceIdentity, Object> identity = getGitResourceIdentity(baseRepoPath, filePath);\n\n                    resourceMap.put(identity.getT1(), identity.getT2());\n                });\n","sourceCodeStart":686,"sourceCodeEnd":722,"githubUrl":"https://github.com/appsmithorg/appsmith/blob/8cd9021c24cdbea1c3c12c966073708e83db60c2/app/server/appsmith-git/src/main/java/com/appsmith/git/files/FileUtilsCEImpl.java#L686-L722","documentation":"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.'","triggerScenarios":"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.","commonSituations":"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.","solutions":["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).","Check the repo's metadata.json for the fileFormatVersion field and compare to the running server's supported version.","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.","Keep all environments that share a git remote on the same (or newer) Appsmith version to avoid forward-incompatible reads."],"exampleFix":"// before\n# repo metadata.json: \"fileFormatVersion\": 3\n# running server supports: up to 2  -> INCOMPATIBLE\n\n// after\n# upgrade server to a release supporting fileFormatVersion >= 3\n# (then re-run connect/pull/import)","handlingStrategy":"validation","validationCode":"# Pre-flight: compare repo fileFormatVersion to the running server's max.\nrepo_version=\"$(jq -r '.fileFormatVersion' repo/metadata.json)\"\nserver_max=\"$(get_supported_fileFormatVersion)\"\n[ \"$repo_version\" -le \"$server_max\" ] \\\n  || echo \"reject: repo format $repo_version > server max $server_max\"","typeGuard":"// Java-side check mirroring isFileFormatCompatible\nboolean isCompatible(Integer saved, int serverMax) {\n  return saved != null && saved <= serverMax;\n}","tryCatchPattern":"try {\n  fileUtils.fetchGitResourceMap(baseRepoPath);\n} catch (AppsmithPluginException e) {\n  if (e.getCode() == AppsmithPluginError.INCOMPATIBLE_FILE_FORMAT) {\n    log.error(\"Repo fileFormatVersion too new; upgrade this instance.\");\n  }\n  throw e;\n}","preventionTips":["Keep all environments sharing a git remote on the same or newer Appsmith version.","Before importing/connecting a repo, check its metadata.json fileFormatVersion against the target server.","Avoid downgrading Appsmith below the version that authored apps in the repo.","If stuck on an older server, re-export apps from a compatible version rather than reading a newer repo."],"tags":["git","versioning","file-format","upgrade","java"],"backgroundTag":null,"analyzedSha":"8cd9021c24cdbea1c3c12c966073708e83db60c2","analyzedAt":"2026-08-12T22:14:19.293Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}