bytedance / bytedance/deer-flow

Legacy .doc files are advertised as supported, but conversion is not reliable

Open
#2,002 0 comments 2 reactions 2 assignees Claimed by @foreleven View on GitHub
Dominant language
Python
Stars
82.4k
Forks
11.4k
Avg merge
2d 5h
Merged PRs (30d)
313

Description

## Summary

Legacy Word `.doc` files are currently advertised as supported upload/convertible documents, but the existing implementation does not reliably handle them.

In practice, `.docx` converts normally, while `.doc` does not have a dedicated or dependable conversion path.

## Expected behavior

Both `.doc` and `.docx` should be handled consistently.

At minimum:

- `.docx` should continue to convert normally
- `.doc` should either:
- be converted through a supported fallback pipeline, or
- fail explicitly with a clear unsupported-environment / unsupported-format message

The system should not silently accept a `.doc` upload while failing to produce usable markdown.

## Actual behavior

`.doc` is included in the supported/convertible extension list, but the conversion path is not actually reliable for legacy Word files.

Observed behavior:

- `.docx` converts successfully
- `.doc` does not have a dedicated fallback conversion path
- `.doc` conversion currently depends on the generic `markitdown` path
- when conversion fails, upload may still be reported as successful, but no markdown output is produced
- the system does not clearly signal that legacy `.doc` is unsupported in the current environment

## Root cause

The upload/conversion layer includes `.doc` in `CONVERTIBLE_EXTENSIONS`, but the implementation only invokes a generic `MarkItDown().convert(...)` path and does not provide a legacy Word fallback such as:

- `soffice` / LibreOffice
- macOS `textutil`
- any explicit `.doc -> .docx` preprocessing step

The underlying conversion stack has clear support for `.docx`, but not a reliable project-level path for `.doc`.

## Impact

- user-facing behavior is inconsistent
- supported-format documentation is misleading
- legacy Word uploads are unreliable
- failures are not surfaced clearly enough
- users may believe `.doc` was processed successfully when no valid markdown was generated

## Proposed fix

Add an explicit `.doc` handling path before generic parsing.

Suggested order:

1. If the file is `.doc`, first try converting `.doc -> .docx`
2. Prefer `soffice` / LibreOffice when available
3. On macOS, fall back to `textutil` when available
4. If no supported converter exists, return a clear failure instead of relying on generic conversion
5. Preserve existing `.docx` behavior unchanged

## Regression tests

Add tests for:

- successful `.doc` fallback conversion
- explicit failure when no `.doc` converter is available
- existing `.docx` conversion behavior remains unchanged
- upload response does not silently report `.doc` conversion success without markdown output

## Reproduction

1. Upload a legacy `.doc` file
2. Trigger markdown extraction / document parsing
3. Observe that:
- `.docx` succeeds
- `.doc` does not have reliable conversion behavior
- failure is not clearly surfaced to the caller

## Notes

If maintainers agree, I’d like to submit a PR for this.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.