Image Parser output is not converted into chunks by Token Chunker

[pramudyalyza]

Hi I'm currently using RAGFlow v0.25.6 and I'm trying to create a custom ingestion pipeline

Since it's just for testing first i tried to create a simple one like this:
Parser → Token Chunker → Indexer

For image files, the Parser is configured to use either OCR or a VLM. I tested both and encountered the same behavior. When I run the pipeline with a PNG image, the Parser successfully extracts the image content and returns it under json:

{
  "chunks": [],
  "html": "",
  "json": [
    {
      "text": "Schedule Trigger\nGet Taxonomy\nFetch Item\nSplit Item...",
      "doc_type_kwd": "image",
      "img_id": "..."
    }
  ],
  "markdown": "",
  "text": ""
}

However, the Token Chunker finishes successfully but produces:

{
  "chunks": []
}

There is no error in the Token Chunker log:

[Parser]:
Start to work on an image.
Done

[Token Chunker]:
Start to split into chunks.
Done.
Done

The same behavior occurs whether I use OCR or a VLM for the image parser. I also tested the custom pipeline directly from the pipeline editor and through a dataset configured to use the custom pipeline.

When a Metadata Transformer was included between the Token Chunker and Indexer, dataset ingestion failed with:

[ERROR][ERROR]: 'text'

After removing the Metadata Transformer, the pipeline completes successfully, but the final chunks array is still empty.

I may be misunderstanding the intended data flow between the Parser and Token Chunker, so I would appreciate clarification on the recommended configuration. Thank you.

[lizuju]

From the 0.25.6 code, the image parser output you pasted should be chunkable by TokenChunker.

The relevant path is:

• Parser._image() emits json like [{ "text": ..., "doc_type_kwd": "image" }]
• TokenChunkerFromUpstream maps the upstream json field to json_result
• _build_json_chunks() treats doc_type_kwd == "image" as an image chunk
• _finalize_json_chunks() emits it as long as the final text is not empty

So for an input like this:

{
  "output_format": "json",
  "json": [
    {
      "text": "Schedule Trigger...",
      "doc_type_kwd": "image",
      "img_id": "..."
    }
  ]
}

I would expect the token chunker to produce roughly:

{
  "chunks": [
    {
      "text": "Schedule Trigger...",
      "doc_type_kwd": "image",
      "img_id": "..."
    }
  ]
}

If you are getting {"chunks": []}, I would first check the actual input payload received by the Token Chunker in the run result, not only the Parser output. In particular, verify that the Token Chunker input still contains the non-empty json array. If the edge/mapping is only passing text, markdown, html, or an empty value, the chunker will finish successfully but has nothing to split.

The Metadata Transformer error ('text') points in the same direction: that component probably received an item shape it did not expect, or it was connected to the wrong variable. After Token Chunker, the next component should consume chunks, not the original Parser json object.

A quick sanity check would be to run with only:

Parser -> Token Chunker

then expand the Token Chunker node details and compare:

1. Token Chunker input: does it contain json[0].text?
2. Token Chunker output: does it emit chunks[0].text?

If the input contains the exact json you pasted and the output is still empty, then I think that is a bug worth filing with the Token Chunker input/output JSON attached, because the 0.25.6 implementation should not drop that image text.

[lizuju]

Thanks, that output is useful. One important distinction: the object you pasted looks like the Token Chunker node's final/merged run output, not necessarily the exact raw input that the Token Chunker received.

The json field being present in that displayed object does not by itself prove the chunker ran on that field. chunks: [] is the chunker's own output, while the UI/runtime may still be showing upstream fields such as json beside it.

From the current implementation, if Token Chunker receives this as its actual input:

{
  "output_format": "json",
  "json": [
    {
      "text": "...",
      "doc_type_kwd": "image",
      "img_id": "..."
    }
  ],
  "name": "Screenshot 2026-07-05 175128.png"
}

then it should produce an image chunk. The Python path takes json_result = from_upstream.json_result or [], builds chunks from doc_type_kwd == "image", then finalizes them into chunks.

So I would check the actual payload immediately before Token Chunker, not the node's final output. I don't know of a UI control that always exposes the raw pre-node input. In a self-hosted setup the most direct check is to add a temporary log around the Token Chunker input point, before validation/invocation:

• Python path: right before TokenChunkerFromUpstream.model_validate(kwargs) in rag/flow/chunker/token_chunker.py
• Go ingestion path, if your pipeline is using it: right at the start of TokenChunkerComponent.invoke(..., inputs) in internal/ingestion/component/chunker/token.go

What you want to confirm is:

1. does the Token Chunker input have output_format: "json"?
2. does it have a non-empty json array at that moment?
3. is json[0].text still non-empty?

If all three are true and the output is still chunks: [], then I would file it as a Token Chunker bug with that exact input/output pair. If the raw input is already missing json, or is marked as output_format: "chunks" with an empty chunks field, then the problem is earlier in the edge/mapping/runtime handoff rather than in the image parser itself.

[pramudyalyza]

Thanks, I added the temporary log like this:

print("TOKEN_CHUNKER_RAW_KWARGS:", kwargs, flush=True)
from_upstream = TokenChunkerFromUpstream.model_validate(kwargs)

I reran the pipeline with the same PNG image and here is the raw token chunker input from the log:

TOKEN_CHUNKER_RAW_KWARGS: {
  'html': '',
  'json': [
    {
      'text': '田\nE\nSchedule Trigger\nGet Texono\nFetch ltem\nSplit Item\nIF Not Empty\nAggregatl\nSet Data2\nExecute Sub Workflon\n(Deactivated)\nGET:1\nipc/lapltesi.alge\nrkllow: KYUTVIG1PURVP.',
      'doc_type_kwd': 'image',
      'img_id': 'imagetemps-83f14d867a9e11f182b1f58af7b85a6b'
    }
  ],
  'markdown': '',
  'text': '',
  '_created_time': 1816529.642201026,
  'file': {
    'created_at': 1783495646.7677143,
    'created_by': '8d99bb405a7611f196b51b660cc67c94',
    'extension': 'png',
    'id': '78492f3a7a9e11f1b459ed2f679879b0',
    'mime_type': 'image/png',
    'name': 'Screenshot 2026-07-05 175128.png',
    'preview_url': None,
    'size': 52459
  },
  'name': 'Screenshot 2026-07-05 175128.png',
  '_elapsed_time': 2.914156927028671,
  'output_format': 'text'
}

So the token chunker does receive a non-empty json array, and json[0].text is non-empty. However, i noticed that the raw input has:

'output_format': 'text'

instead of:

'output_format': 'json'

Could this be why the token chunker is not using the json field and returns chunks: []?

If the token chunker requires output_format: "json" for image chunks, how can i configure the parser node to emit output_format: "json" in the UI for image? in the parser node UI, i don't see an option to change the image parser output format to json. Please advise on how to solve this. Thank you!

[lizuju]

Yes, that explains the empty chunks.

With that raw input, Token Chunker will not use the json field. The branch is selected from output_format first:

if from_upstream.output_format in ["markdown", "text", "html"]:
    payload = getattr(from_upstream, f"{from_upstream.output_format}_result") or ""
    ...
    return

Since the input says output_format: "text", it reads the empty text field, sets chunks to [], and returns before the JSON branch is reached. The non-empty json array is still present in the payload, but it is not the active payload according to output_format.

The strange part is that this should not be something you need to configure in the UI for images. In the current parser code, the image path already does:

self.set_output("output_format", "json")
...
self.set_output("json", json_result)

and the image parser default config also has output_format: "json". So I would not look for a parser-node UI switch first. The parser appears to produce JSON, but somewhere between Parser output and Token Chunker input, output_format is being overwritten to text while the json field is still carried along.

For a quick local confirmation, temporarily force it before validation:

kwargs["output_format"] = "json"
from_upstream = TokenChunkerFromUpstream.model_validate(kwargs)

If chunks appear after that, the bug is confirmed in the flow handoff / edge mapping, not OCR and not the Token Chunker's JSON conversion logic.

A useful issue report would include:

• Parser output for the PNG
• Token Chunker raw kwargs showing output_format: "text" plus non-empty json
• Token Chunker output showing chunks: []

The clean fix should preserve the parser's active output_format as json when json is the non-empty upstream result. A Token Chunker fallback like "prefer non-empty json when text is empty" would work as a workaround, but it would hide the real mapping problem.

[pramudyalyza]

Thanks, Gavin. I tested the quick local confirmation by temporarily forcing:

kwargs["output_format"] = "json"
from_upstream = TokenChunkerFromUpstream.model_validate(kwargs)

After doing that, the image chunking works.

So this seems to confirm that the issue is in the flow handoff / edge mapping, where output_format is being overwritten to "text" before reaching the Token Chunker, even though the json field is non-empty.

Should I open a separate bug issue for this?

[lizuju]

Yes, this is specific enough for a bug issue now. The forced output_format = "json" result isolates the failure to the flow handoff rather than OCR or JSON chunk construction.

I would include:

• the RAGFlow version or commit
• the minimal Parser -> Token Chunker -> Indexer pipeline JSON
• the raw Token Chunker kwargs showing output_format: "text" alongside a non-empty json
• the empty chunks result
• the successful result after temporarily forcing output_format to json

A focused title would be: Flow handoff overwrites image parser output format from JSON to text.

Link this discussion from the issue so the investigation is preserved. The temporary assignment is useful proof, but I would remove it after collecting the evidence; the fix belongs where the parser output metadata is mapped into the next component.