Gen2: Encoding issue with special characters in path parameters

Version info

node: v18.16.0
firebase-functions: v4.4.1
firebase-tools: v12.5.2
firebase-admin: v11.8.0

Steps to reproduce

This issue was not encountered in gen1, and special characters in path parameters were correctly encoded.

Deploy a Firebase Cloud Function Gen2 using a Firestore trigger as follows:

import { log } from "firebase-functions/logger";
import { onDocumentUpdated } from "firebase-functions/v2/firestore";

export const testPlanet = onDocumentUpdated("planetes/{planeteId}", async (event) => {
  log(event.params.planeteId);
});

Ensure that the planeteId document contains special characters such as "é", "è", "à", etc. Example: "Helvétios", "Électre".
Observe the planeteId value in the deployed function

Expected behavior

The planeteId value should be correctly encoded and displayed in UTF-8, preserving special characters such as "é", "è", "à", etc., in the deployed Firebase Cloud Function Gen2.

Actual behavior

After deploying the Firebase Cloud Function Gen2, the planeteId value appears to be incorrectly encoded, resulting in a value like Helvétios becoming HelvÃ©tios or Électre becoming Ã�lectre.

Were you able to successfully deploy your functions?

Yes, the deployment was successful without any error messages.

I found a few problems with this issue:

I couldn't figure out how to label this issue, so I've labeled it for a human to triage. Hang tight.
This issue does not seem to follow the issue template. Make sure you provide all the required information.

@Llolow

Hi @Llolow. I don't have a solution yet, but I wanted to share an update.

It looks like the issue you've found goes beyond Cloud Functions for Firebase, and I'm in conversations with other teams at GCP to find the underlying issue. Thanks for your patience.

@taeold

Hello @taeold, thanks for the answer.

I will use for the moment the fact than gen1 and gen2 functions can coexist

@Llolow

@Llolow Sorry for not responding sooner.

I've learned since then that event.document will contains that's formatted as octal-encoded UTF-8 string. To retrieve the "actual" document path, then, you can convert the bytes as utf-8 string:

const planetId = Buffer.from(event.params.planeteId, "binary").toString("utf-8")

I would agree with you to think that this is pretty tricky. Let me try and see if we can come up with a way to do the conversion in the SDK itself so you don't have to bother with these kind of problems.

@taeold

Hi @taeold ,
We were just hit by this too. It's definitely a regression when migrating from v1 to v2, and it ought to be noted in the migration document that you can no longer rely on the 'params' when using special characters (even non-ascii ansi characters like Å).
If we add a workaround like the above - how will that effect a possible future fix? Will the workaround then break?

Also: I definitely don't consider this to be a feature request, but a serious bug that affects real-life usage of Cloud Functions v2.

@taeold

Hi again @taeold ,
In my own testing, the workaround you suggest can be 'dangerous' in case the underlying issue is suddenly fixed:

Taking the string "SDÅV" as an example:
Suggested workaround:

d = Buffer.from("SDÃ�V", "binary").toString("utf-8")
'SDÅV'

Application of the suggested workaround in case the parameter is already in utf-8:

e = Buffer.from("SDÅV", "binary").toString("utf-8")
'SD�V'

Hey, this is an issue for us as well.

If the document id in event.params doesn't 100% match that of the actual firestore document, then this must surely be a bug in the SDK?

Same issue here. Definitely a bug if v1 and v2 behave differently.

@mortenbekditlevsen

This issue affects us as well. I baked a solution with AI that overcomes the problem stated by @mortenbekditlevsen, while google doesn't come up with a patch. (This is major for non-english speakers, guys!)

It uses the iconv-lite library.

const iconv = require('iconv-lite');

function fixMojibake(str) {
  // Detects typical mojibake patterns UTF-8 → Latin1
  const isLikelyUtf8Mojibake =
    /Ã[a-zA-Z]|Ã¢|Ã£|Ãª|Ã©|Ã§|Ã³|Ã¡|Ã|Ãº|Ã¼|Ã|Ã±|Ã�|Ã‰|Ã“|Ãš|Ã‹|Â|â‚¬|â€œ|â€�|â€˜|â€™|â€”|�/.test(
      str
    );
  if (!isLikelyUtf8Mojibake) return str;

  const buffer = Buffer.from(str, 'latin1'); // Treats each char as a ISO-8859-1 byte 
  return iconv.decode(buffer, 'utf8'); // decodes chars as UTF-8
}

I did not test it extensively, just enough for my use cases.

I solved it like this:

function toUTF8<T extends string>(value: T): string {
	return Buffer.from(value, "binary").toString("utf-8");
}

export function fixEncoding<T extends Record<string, any> & { params: Record<string, string> }, K extends keyof T>(
	event: T,
	props: K[]
): void {
	// Fix encoding on all event params
	for (const param of Object.keys(event.params)) {
		event.params[param] = toUTF8(event.params[param]);
	}

	// Fix enconding on any specified event properties
	for (const prop of props) {
		const val = event[prop];
		if (val) {
			(event[prop] as string) = toUTF8(val);
		}
	}
}

And then inside the function, in the very beginning, I just call fixEncoding with the event object and any extra properties that I know can have encoding issues:

fixEncoding(event, ["ref"]);

Any update on this for fixing the underlying issue without us needing a work around? I am having this issue with emojis!

@cachefulton

@cachefulton I have got a potential fix in for this which seems to work for all examples discussed in this issue. I have also tested it with some emojis and other cases such as Arabic, Mandarin etc.

I will provide updates here as soon as possible.

Any progress on this? This is affecting our onValueWritten Firebase functions and we would love to drop the need for a workaround.

@adegruchy

Hi @adegruchy, thanks for pinging on this, sorry it has been inactive. I have started looking into this again to see if we can fix purely in the SDK. I will provide updates as soon as I have them.

Thank you!

Navigation Menu

Repository navigation

Gen2: Encoding issue with special characters in path parameters #1459

Version info

Steps to reproduce

Expected behavior

Actual behavior

Were you able to successfully deploy your functions?

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Gen2: Encoding issue with special characters in path parameters #1459

Description

Version info

Steps to reproduce

Expected behavior

Actual behavior

Were you able to successfully deploy your functions?

Activity

google-oss-bot commented on Sep 6, 2023

taeold commented on Sep 18, 2023

Llolow commented on Sep 28, 2023

taeold commented on Oct 23, 2023

mortenbekditlevsen commented on Dec 22, 2023

mortenbekditlevsen commented on Dec 22, 2023

adamxi commented on May 29, 2024

albertopq commented on Sep 4, 2024

Padreco-lbr commented on May 21, 2025

adamxi commented on May 22, 2025

cachefulton commented on May 27, 2026

IzaakGough commented on Jun 17, 2026

adegruchy commented on Oct 20, 2026

IzaakGough commented on Oct 22, 2026

adegruchy commented on Oct 22, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions