Issue Station
Sign In
Tools hereToolbox

fastapi - ✅(Solved) Fix Docs: No guidance on Pandas DataFrame serialization — numpy types cause JSON errors [1 pull requests, 1 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
fastapi/fastapi#15085•Fetched 2026-04-08 00:21:35
View on GitHub
Comments
0
Participants
1
Timeline
3
Reactions
0
Author
anix-lynchanix-lynch
Participants
anix-lynchanix-lynch
Timeline (top)
converted_to_discussion ×1cross-referenced ×1locked ×1

The encoder.md tutorial covers jsonable_encoder for Pydantic models and Python datetime objects, but does not mention Pandas DataFrames — a very common data source in FastAPI apps (ML pipelines, analytics APIs, data science backends).

Error Message

TypeError: Object of type int64 is not JSON serializable

Root Cause

Pandas is extremely common in FastAPI backends (ML inference APIs, analytics dashboards, data pipelines). This silent failure is a frequent gotcha for developers and is not covered anywhere in the current docs.

Proposing a small addition to docs/en/docs/tutorial/encoder.md under a new "Working with Pandas DataFrames" section.

Fix Action

Fixed

PR fix notes

PR #15086: docs: add Pandas DataFrame serialization guidance to encoder.md

Description (problem / solution / changelog)

Summary

Closes #15085

Adds a new section "Working with Pandas DataFrames" to docs/en/docs/tutorial/encoder.md.

Problem

Pandas is one of the most common data sources in FastAPI backends (ML APIs, analytics, data pipelines). However, the existing encoder.md doc only covers Pydantic models and Python datetime — it says nothing about Pandas DataFrames.

When developers call df.to_dict(orient="records") and return the result directly, they hit:

TypeError: Object of type int64 is not JSON serializable

This happens because Pandas uses NumPy types internally (numpy.int64, numpy.float64, numpy.nan, pandas.NaT) which are not JSON-serializable by default. This is a very common gotcha with no existing docs coverage.

Changes

Added two safe patterns to encoder.md:

  1. jsonable_encoder(df.to_dict(orient="records")) — wraps the dict output so FastAPI converts numpy types + NaT/NaN → null
  2. json.loads(df.to_json(orient="records", date_format="iso")) — uses pandas native serializer, handles all numpy types natively

Both approaches are shown with a practical healthcare analytics API example (the real-world context where this was discovered).

Checklist

  • Added new section ## Working with Pandas DataFrames to encoder.md
  • Showed ❌ broken pattern and ✅ two safe alternatives
  • Added /// tip note on date_format="iso" for datetime consistency
  • Added /// note on NaN/NaT → null behavior
  • Doc-only change, no code changes

Changed files

  • docs/en/docs/tutorial/encoder.md (modified, +67/-0)

Code Example

TypeError: Object of type int64 is not JSON serializable

---

from fastapi import FastAPI
import pandas as pd

app = FastAPI()

@app.get("/data")
def get_data():
    df = pd.DataFrame({
        "count": [1, 2, 3],        # numpy.int64
        "score": [1.5, float("nan"), 3.0],  # numpy.float64 + NaN
    })
    return df.to_dict(orient="records")  # 💥 NaN breaks JSON, int64 may fail

---

from fastapi.encoders import jsonable_encoder

@app.get("/data")
def get_data():
    df = pd.DataFrame({...})
    # ✅ Converts numpy types + handles NaT/NaN -> null
    return jsonable_encoder(df.to_dict(orient="records"))

---

import json

@app.get("/data")
def get_data():
    df = pd.DataFrame({...})
    # ✅ pandas handles numpy types natively
    return json.loads(df.to_json(orient="records", date_format="iso"))
RAW_BUFFERClick to expand / collapse

Summary

The encoder.md tutorial covers jsonable_encoder for Pydantic models and Python datetime objects, but does not mention Pandas DataFrames — a very common data source in FastAPI apps (ML pipelines, analytics APIs, data science backends).

The Problem

When returning data from a Pandas DataFrame using .to_dict(orient="records"), columns retain NumPy types (numpy.int64, numpy.float64, numpy.nan, pandas.NaT). These are not natively JSON serializable, causing runtime errors:

TypeError: Object of type int64 is not JSON serializable

Or silently producing invalid JSON with NaN values (not valid JSON spec).

Minimal Reproduction

from fastapi import FastAPI
import pandas as pd

app = FastAPI()

@app.get("/data")
def get_data():
    df = pd.DataFrame({
        "count": [1, 2, 3],        # numpy.int64
        "score": [1.5, float("nan"), 3.0],  # numpy.float64 + NaN
    })
    return df.to_dict(orient="records")  # 💥 NaN breaks JSON, int64 may fail

Expected

Docs should show the safe pattern for returning Pandas DataFrames:

from fastapi.encoders import jsonable_encoder

@app.get("/data")
def get_data():
    df = pd.DataFrame({...})
    # ✅ Converts numpy types + handles NaT/NaN -> null
    return jsonable_encoder(df.to_dict(orient="records"))

Or alternatively using pandas native JSON serialization:

import json

@app.get("/data")
def get_data():
    df = pd.DataFrame({...})
    # ✅ pandas handles numpy types natively
    return json.loads(df.to_json(orient="records", date_format="iso"))

Why This Matters

Pandas is extremely common in FastAPI backends (ML inference APIs, analytics dashboards, data pipelines). This silent failure is a frequent gotcha for developers and is not covered anywhere in the current docs.

Proposing a small addition to docs/en/docs/tutorial/encoder.md under a new "Working with Pandas DataFrames" section.

Environment

  • FastAPI: latest
  • Python: 3.11
  • pandas: 2.x
  • Hit this while building a healthcare analytics REST API backed by a pandas DataFrame

extent analysis

Problem Summary

FastAPI’s default JSON encoder can’t handle NumPy/Pandas scalar types (int64, float64, NaN, NaT). Returning df.to_dict(orient="records") therefore raises TypeError or emits invalid JSON.

Root Cause Analysis

jsonable_encoder only knows how to convert standard Python types. Pandas columns keep NumPy dtypes, and float('nan')/pd.NaT are not JSON‑serialisable, so the response fails.

Fix Plan

1️⃣ Use jsonable_encoder (recommended)

from fastapi import FastAPI
from fastapi.encoders import jsonable_encoder
import pandas as pd

app = FastAPI()

@app.get("/data")
def get_data():
    df = pd.DataFrame({
        "count": [1, 2, 3],                     # numpy.int64
        "score": [1

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#api#ssr#installation#tensor shape#autograd error#model save/load#runtime error

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING