Comments in JSON: “Unexpected token / in JSON”
Updated
Comments are for code. This is data. JSON has no comment syntax at all, neither // nor /* */, so a strict parser treats the first slash as a character that has no business being there and stops.
The error and the fix
A config file that grew a note. Fine in JavaScript, fine in a .jsonc file, an error in JSON:
{
// local runs only
"port": 8080,
"debug": true /* remove before release */
}Delete both comments. If the note matters, keep it as data, under a key your program ignores:
{
"_comment": "local runs only",
"port": 8080,
"debug": true
}Whether a JSON file may contain comments in general, and what JSONC and JSON5 are, is a separate question with its own guide: comments in JSON, JSONC and JSON5. This page is about the error and how to get rid of it.
Why a comment breaks JSON
RFC 8259 lists everything a JSON text is made of: six structural characters, strings, numbers, the three literals and insignificant whitespace, which is exactly space, tab, line feed and carriage return. Comments are not on the list and not in the grammar, so / can only be an unexpected character. JSON’s author dropped comments on purpose, after people started using them to pass parsing instructions; a format without them stays the same in every parser.
Comment error messages by parser
A line comment where a key is expected, line 2 of the example { // note above, and a block comment before the document, /* x */ {}. Hardly any parser says the word “comment”.
| Parser | Inside an object (line 2) | Before the document: /* x */ {} |
|---|---|---|
| Chrome, Edge, Node.js (V8) | Expected property name or '}' in JSON at position 4 (line 2 column 3) | Unexpected token '/', "/* x */ {}" is not valid JSON |
| Node.js 18, older Chrome (V8 10.2) | Unexpected token / in JSON at position 4 | Unexpected token / in JSON at position 0 |
| Firefox | JSON.parse: expected property name or '}' at line 2 column 3 of the JSON data | JSON.parse: unexpected character at line 1 column 1 of the JSON data |
| Safari | JSON Parse error: Unrecognized token '/' | JSON Parse error: Unrecognized token '/' |
| Python | Expecting property name enclosed in double quotes: line 2 column 3 (char 4) | Expecting value: line 1 column 1 (char 0) |
| Go (encoding/json) | invalid character '/' looking for beginning of object key string | invalid character '/' looking for beginning of value |
| Java (Jackson 2) | Unexpected character ('/' (code 47)): maybe a (non-standard) comment? (not recognized as one since Feature 'ALLOW_COMMENTS' not enabled for parser) | The same message, line 1, column 1 |
| C# (System.Text.Json) | '/' is invalid after a value. Expected either ',', '}', or ']'. | '/' is an invalid start of a value. |
| C# (Newtonsoft.Json) | No error: comments are skipped | No error: comments are skipped |
| PHP (json_decode) | Syntax error, json_last_error() 4 | Syntax error, json_last_error() 4 |
| Rust (serde_json) | key must be a string at line 2 column 3 | expected value at line 1 column 1 |
| jq | jq: parse error: Invalid numeric literal at line 2, column 5 | jq: parse error: Invalid numeric literal at line 1, column 3 |
| Visual Studio Code | Comments are not permitted in JSON., problem 521 | Comments are not permitted in JSON., problem 521 |
Only Jackson and Visual Studio Code recognise a comment; System.Text.Json’s “invalid after a value” right after { is simply misleading. Checked by running: Node.js 18, 24 and 25.1, Safari 27, Python 3.9 and 3.14, Go 1.25–1.27, Jackson 2.22 and 3.2, System.Text.Json and Newtonsoft.Json 13.0.4, PHP 8.3 and 8.5, serde_json 1.0, jq 1.7 and 1.8. Firefox and Visual Studio Code: from their source code; Firefox’s messages are also listed on Mozilla’s reference pages.
Files that look like JSON but allow comments
- Visual Studio Code settings (
settings.json,launch.json) andtsconfig.jsonare JSONC (JSON with Comments): comments are allowed there because their own readers skip them. package.jsonis plain JSON: npm reads it with a strict parser, so a comment breaks installs..json5files are JSON5, which also allows comments, single quotes and trailing commas.- Copy anything from those files into an API request or a strict parser and the comments become errors.
A # comment, as in YAML or shell, is not a comment in any of these formats; this site’s validator reports it as an unexpected character.
How to read JSON with comments in code
Two honest options: remove the comments where the file is produced, or read the file with a parser that understands comments (System.Text.Json has a switch for it: allow some kinds of invalid JSON). The dishonest option is a regular expression, and the Python snippet shows why.
Python
import json
import re
text = '{\n // where to send reports\n "url": "https://example.com/hook"\n}'
naive = re.sub(r"//.*", "", text) # also cuts "//example.com/hook"
try:
json.loads(naive)
except json.JSONDecodeError as e:
print(e.msg) # Invalid control character at: the cut string runs into a line break
import json5 # pip install json5: understands comments
print(json5.loads(text)["url"]) # https://example.com/hookJavaScript
// npm install jsonc-parser: the parser behind Visual Studio Code settings
import { parse } from "jsonc-parser";
const text = '{\n // where to send reports\n "url": "https://example.com/hook"\n}';
const errors = [];
console.log(parse(text, errors).url, errors.length); // https://example.com/hook 0Go
package main
import (
"encoding/json"
"fmt"
"github.com/tailscale/hujson"
)
func main() {
text := []byte("{\n // where to send reports\n \"url\": \"https://example.com/hook\"\n}")
std, err := hujson.Standardize(text) // strips comments, keeps byte offsets
var v map[string]string
fmt.Println(err, json.Unmarshal(std, &v), v["url"]) // <nil> <nil> https://example.com/hook
}C#
using System.Text.Json;
var options = new JsonDocumentOptions { CommentHandling = JsonCommentHandling.Skip };
using var doc = JsonDocument.Parse("{\n // local runs only\n \"port\": 8080\n}", options);
Console.WriteLine(doc.RootElement.GetProperty("port")); // 8080Java (Jackson)
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.node.ObjectNode;
// Notes kept as data survive any parser; drop them after reading.
ObjectNode node = (ObjectNode) new ObjectMapper().readTree("{\"_comment\": \"local runs only\", \"port\": 8080}");
node.remove("_comment");
System.out.println(node); // {"port":8080}Jackson skips // and /* */ with JsonReadFeature.ALLOW_JAVA_COMMENTS, the current name of the ALLOW_COMMENTS feature from its error message.
PHP
$data = json_decode('{"_comment": "local runs only", "port": 8080}', true);
unset($data['_comment']);
echo json_encode($data); // {"port":8080}How to keep comments out of JSON
- Keep human notes in a separate document or in
"_comment"keys, not in comments. - If a config really needs comments, name it
.jsoncor.json5so editors and people know which parser it takes. - Strip comments with a real JSONC parser, never with a regular expression:
//appears in every URL. - Validate the file you ship, not the one you edit, in the JSON validator.
Try it in the validator
Open a sample with a comment in the JSON validator. It reports the code comment where the // or /* starts, wherever a value, a key, a comma or a bracket was expected. After a key it reports a missing colon, and after the end of the document extra data, because that is what the parser was waiting for there.
Related: trailing comma, comments in JSON, JSONC and JSON5, and all JSON errors.
JSON comment error FAQ
Does JSON support comments?
No. RFC 8259 has no comment syntax. JSONC and JSON5 add comments, but they are different formats and need their own parsers.
Why does my editor accept comments in settings.json?
Because that file is JSONC, read by a parser that skips comments. Visual Studio Code still reports “Comments are not permitted in JSON.” in files it treats as plain JSON.
How do I add a note to a JSON file?
As data: a key such as "_comment" with a string value. Every parser reads it; your program just ignores that key.
Is it safe to remove comments with a regular expression?
No. // and /* can appear inside strings, URLs above all, and a regular expression can’t tell. Use a JSONC or JSON5 parser instead.