Unable to locate a matching service definition from file

Error message

Unable to locate a matching service definition from file [{}]. Reloading cache...

What it means

DeleteResourceBasedRegisteredServiceWatcher.accept handles service file deletions. It parses the deleted file to find the matching registered service; if none is found in memory, it logs this warning and falls back to a full cache reload (serviceRegistryDao.load()) plus a CasRegisteredServicesLoadedEvent to resynchronize.

Solutions

No action strictly required — CAS reloads the whole cache automatically to resync.
Ensure filename ids match the JSON 'id' fields so future deletes resolve directly.
Avoid bulk file operations while CAS is running; perform them during maintenance windows and then trigger a registry reload.

Defensive patterns

Strategy: fallback

Prevention

Match filename ids with JSON 'id' fields so delete events resolve without full reloads.
Batch or stagger external file deletions (rsync/git) rather than racing the watcher.
Rely on the automatic cache reload; verify registry state after bulk deletions.

When it happens

Trigger: A service file is deleted from the watched directory while the corresponding RegisteredService is not present in the in-memory registry (e.g. file never loaded, id mismatch, stale watcher event); findServiceBy lookup returns null.

Common situations: Deleting files by hand before CAS finished loading; filename id not matching the JSON id so the lookup misses; external sync tools (rsync, git checkout) deleting files mid-run.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

AI-assisted analysis of apereo/cas@e7288fc434 (2026-09-08). Data as JSON: /api/errors/23161f49289d2a7b. Report an issue: GitHub.

Appendix: source

Thrown at core/cas-server-core-services-registry/src/main/java/org/apereo/cas/services/resource/DeleteResourceBasedRegisteredServiceWatcher.java:37

    public DeleteResourceBasedRegisteredServiceWatcher(final AbstractResourceBasedServiceRegistry serviceRegistryDao) {
        super(serviceRegistryDao);
    }

    @Override
    public void accept(final File file) {
        val fileName = file.getName();
        if (!(!fileName.isEmpty() && fileName.charAt(0) == '.') && Arrays.stream(serviceRegistryDao.getExtensions()).anyMatch(fileName::endsWith)) {
            LOGGER.debug("Service definition [{}] was deleted. Reloading cache...", file);
            val service = serviceRegistryDao.getRegisteredServiceFromFile(file);
            val clientInfo = ClientInfoHolder.getClientInfo();
            if (service != null) {
                serviceRegistryDao.publishEvent(new CasRegisteredServicePreDeleteEvent(this, service, clientInfo));
                serviceRegistryDao.removeRegisteredService(service);
                LOGGER.debug("Successfully deleted service definition [{}]", service.getName());
                serviceRegistryDao.publishEvent(new CasRegisteredServiceDeletedEvent(this, service, clientInfo));
            } else {
                LOGGER.warn("Unable to locate a matching service definition from file [{}]. Reloading cache...", file);
                val results = serviceRegistryDao.load();
                serviceRegistryDao.publishEvent(new CasRegisteredServicesLoadedEvent(this, results, clientInfo));
            }
        }
    }
}

View on GitHub (pinned to e7288fc434)