apache/druid · error · SegmentLoadingException

Failed to get segment factory for

Error message

Failed to get segment factory for %s

What it means

Thrown when the cache's factory.json (segmentizerFactory descriptor) exists for a segment but cannot be deserialized into a SegmentizerFactory due to an IOException (corrupt or unreadable JSON). This file records how to open the locally cached segment; failure blocks loading that segment from cache.

Solutions

1. Delete the corrupt factory.json (or the whole segment directory) in the cache location so the segment re-downloads fresh.
2. Check file permissions/readability for the Druid process user.
3. Look for filesystem errors (dmesg, fsck) if corruption is widespread; restore from a healthy cache or wipe the cache.
4. Retry the load after cleanup; the segment is re-fetched from deep storage and a new factory.json is written.

// pre-check factory.json parseability before loading from cache
new ObjectMapper().readValue(factoryJson, SegmentizerFactory.class); // delete file if this throws

try { loadSegment(segment); } catch (SegmentLoadingException e) { if (e.getMessage().contains("Failed to get segment factory")) { deleteSegmentDir(segment); retryLoad(segment); } }

When it happens

Trigger: getSegmentFactory path: factoryJson.exists() is true but jsonMapper.readValue(factoryJson, SegmentizerFactory.class) throws IOException — truncated/corrupted file (e.g. crash during write) or unreadable permissions.

Common situations: Unclean shutdown while factory.json was being written; disk corruption; cache directory copied/rsynced incorrectly; wrong file permissions after user change.

Understand the failure class

Background: JSON parse error: "Unexpected token" / "not valid JSON" / "failed to parse" — what JSON parsers are really complaining about — this error's family across 45 libraries.

Related errors

• Can not supply empty segments as input, please use either…
• druid.segmentCache.locations must be set on historicals.
• Exception during reading lookups from
• Failed to load segment
• Failed to load segment

AI-assisted analysis of apache/druid@9b90983fd2 (2026-09-07). Data as JSON: /api/errors/62e023b39aa18baf. Report an issue: GitHub.

Appendix: source

Thrown at server/src/main/java/org/apache/druid/segment/loading/SegmentLocalCacheManager.java:2460

            segment.getId(),
            segment.getSize(),
            result.getSize()
        );
      }
    }

    @GuardedBy("entryLock")
    private SegmentizerFactory getSegmentFactory(final File segmentFiles) throws SegmentLoadingException
    {
      final File factoryJson = new File(segmentFiles, "factory.json");
      final SegmentizerFactory factory;

      if (factoryJson.exists()) {
        try {
          factory = jsonMapper.readValue(factoryJson, SegmentizerFactory.class);
        }
        catch (IOException e) {
          throw new SegmentLoadingException(e, "Failed to get segment factory for %s", e.getMessage());
        }
      } else {
        factory = new MMappedQueryableSegmentizerFactory(indexIO);
      }
      return factory;
    }

    @Override
    public boolean equals(Object o)
    {
      if (o == null || getClass() != o.getClass()) {
        return false;
      }
      CompleteSegmentCacheEntry that = (CompleteSegmentCacheEntry) o;
      return Objects.equals(dataSegment, that.dataSegment);
    }

    @Override

View on GitHub (pinned to 9b90983fd2)