serde_json: expected value at line 1 column 1

An example

This code fetches a user and reads the response straight into a struct:

#[derive(Deserialize)]
struct User {
    id: u64,
    name: String,
}

let user: User = reqwest::get("https://api.example.com/users/42")
    .await?
    .json()
    .await?;

If user 42 doesn’t exist, the server answers with a 404 page in HTML. reqwest doesn’t treat a 404 as an error, so it hands the page to serde_json, which stops at the <. If main returns the error through anyhow, the program prints:

Error: error decoding response body

Caused by:
    expected value at line 1 column 1

If you call .unwrap() on the result of serde_json::from_str instead, the same error is printed in its debug form:

called `Result::unwrap()` on an `Err` value: Error("expected value", line: 1, column: 1)

Lines and columns both start at 1, and the column counts bytes rather than characters, so an emoji earlier on the line pushes it along by four. An empty body gives EOF while parsing a value at line 1 column 0 instead, because there was nothing to read.

See what the server actually sent

reqwest makes this harder to track down. Printed the usual way, with {}, its error says only error decoding response body. The serde_json message is underneath, in source(), and {:?} shows it, as does {:#} with anyhow. But neither one shows the body, and the body is what tells you what happened.

Instead of .json(), read the body as text, check the status, and parse it yourself. A failed request then reports what the server actually said:

let resp = reqwest::get(url).await?;
let status = resp.status();
let body = resp.text().await?;

if !status.is_success() {
    anyhow::bail!("{status}: {}", body.chars().take(300).collect::<String>());
}
let user: User = serde_json::from_str(&body).map_err(|e| {
    anyhow::anyhow!("{e}; body starts with {:?}", body.chars().take(100).collect::<String>())
})?;

The status code usually explains it. A 404 means the URL or ID is wrong. A 401 or 403 means the request isn’t authenticated. reqwest follows redirects, so a redirect to a sign-in page arrives as a 200 with HTML in it. A 429 means you’re being rate limited. If the status is 200 and the body is JSON, look for a byte order mark at the start. serde_json doesn’t skip one, so a file saved as “UTF-8 with BOM” fails at column 1 too. body.trim_start_matches('\u{feff}') removes it.

What each message means

Every serde_json error has the same shape: the reason, then at line L column C. These are syntax errors, which mean the text isn’t valid JSON:

The second kind comes from serde. The JSON parsed fine, but a value doesn’t fit your type. For these, the line and column point just after the value that didn’t fit, or after the closing } for a missing field:

To tell the two kinds apart in code, err.classify() returns Category::Syntax, Category::Eof or Category::Data. To find the spot in the JSON, paste both the message and the JSON into the error lookup. It converts serde_json’s byte column for you, which matters when the text has accented letters or emoji.

When the JSON doesn’t fit your struct

The most common data error is missing field `first_name` when the JSON clearly has the data. Rust fields are written in snake_case and most APIs use camelCase, so serde looks for first_name and the JSON has firstName. One attribute on the struct fixes every field. The same idea works for enums, which serde otherwise matches by their exact Rust name:

#[derive(Deserialize)]
#[serde(rename_all = "camelCase")]
struct User {
    id: u64,
    first_name: String,          // reads "firstName"
    #[serde(default)]
    tags: Vec<String>,           // empty if "tags" is missing
    middle_name: Option<String>, // None if missing or null
    status: Status,
}

#[derive(Deserialize)]
#[serde(rename_all = "lowercase")]
enum Status {
    Pending,                     // reads "pending"
    Shipped,
}

An Option field accepts both a missing field and null, so use it for anything the API sometimes leaves out. #[serde(default)] fills in the type’s default value instead. For a single field with an odd name, use #[serde(rename = "user-id")].

For invalid type: string "34", expected u32, the API sends numbers in quotes. If you can’t change it, read the field as a String and convert it, or use DisplayFromStr from the serde_with crate to do the same on the field itself.

A list wrapped in an object

If the whole response fails with invalid type: map, expected a sequence, you asked for a Vec and got an object. Many APIs put the list inside one, next to paging details. Add a small struct for the outer object:

// {"data": [{"id": 1, ...}], "page": 1}
#[derive(Deserialize)]
struct Page {
    data: Vec<User>,
}

let users = serde_json::from_str::<Page>(&body)?.data;

If you don’t know the shape yet, parse into serde_json::Value first and print it, or paste the response into the JSON viewer.

The same error elsewhere