JavaScriptのatobで出るInvalidCharacterErrorの直し方

​​JavaScript​Chromium,Node.js,トラブルシュート

atob() の InvalidCharacterError は、渡した文字列が普通の Base64 として読めないときに出るエラーです。この記事で確かめた原因は、Base64URL の - と _ が混ざっていること、data:…;base64, の先頭の部分が付いたままになっていること、Base64 にしていない文字列を渡していること、Base64 の文字列が途中で切れていることの4つです。原因に合わせて文字列を整えてから atob() に渡すと、エラーは消えます。

JWT(ログインのトークン)のペイロードをブラウザーで読もうとした場面や、FileReader.readAsDataURL() で受け取った data URL をデコードしようとした場面で出ます。私は検証環境でこのエラーをわざと起こし、出たメッセージと、直すと消えることを確かめました。

補足

検証環境は Ubuntu 24.04、Node.js 22.23.4、Playwright 1.63.0 で起動した Chromium 153.0.8010.12(ヘッドレス)です。ブラウザーのエラーは Playwright で取り出しました。Chrome の DevTools の画面での見え方や、Firefox・Safari のメッセージは確かめていません。

Chromium と Node.js で出るメッセージ

Chromium で、次のページを開きました。ボタンをクリックすると、data URL をそのまま atob() に渡します(out は結果を表示する <pre> の要素です)。

js
const dataUrl = 'data:text/plain;base64,aGVsbG8=';

// data URL をそのまま atob に渡す(エラーを捕まえない)
document.getElementById('decode').addEventListener('click', () => {
  out.textContent = atob(dataUrl);
});

ボタンを押すと、次のエラーが出て、画面には何も表示されませんでした。

text
Uncaught InvalidCharacterError: Failed to execute 'atob' on 'Window': The string to be decoded is not correctly encoded.

Node.js でも atob() は使えます。同じ data URL を渡す uncaught.mjs を作りました。

js
// data URL をそのまま atob に渡す(エラーを捕まえない)
const dataUrl = 'data:text/plain;base64,aGVsbG8=';
console.log(atob(dataUrl));

実行すると、次のように止まりました(ファイルの場所は /path/to/app に置き換えています)。uncaught.mjs:3:13 は、atob() を呼んだ3行目です。

console
$ node uncaught.mjs
node:buffer:1306
      throw lazyDOMException('Invalid character', 'InvalidCharacterError');
            ^

DOMException [InvalidCharacterError]: Invalid character
    at atob (node:buffer:1306:13)
    at file:///path/to/app/uncaught.mjs:3:13
    at ModuleJob.run (node:internal/modules/esm/module_job:343:25)
    at async onImport.tracePromise.__proto__ (node:internal/modules/esm/loader:681:26)
    at async asyncRunEntryPointWithESMLoader (node:internal/modules/run_main:117:5)

Node.js v22.23.4

メッセージの文は違いますが、どちらも名前が InvalidCharacterError の DOMException です。MDN の atob() のページにも、渡した文字列が正しい Base64 でないときは InvalidCharacterError の DOMException になると書かれています。

どんな文字列でエラーになるか

いくつかの文字列を atob() に渡し、エラーの名前とメッセージを出しました。

js
// atob に、Base64 として読めない文字列を渡す
const token = 'eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0IiwibmFtZSI6IuOBreOBk-OBvuOCiyJ9.c2lnbmF0dXJl';
const inputs = {
  'Base64(正しい)': 'aGVsbG8=',
  'Base64(= なし)': 'aGVsbG8',
  'data URL のまま': 'data:text/plain;base64,aGVsbG8=',
  'JWT のペイロード': token.split('.')[1],
  'エンコード前の文字列': 'こんにちは',
  '途中で切れた Base64': 'aGVsb',
};
for (const [label, s] of Object.entries(inputs)) {
  try {
    console.log(`${label}: ${JSON.stringify(s)} → 結果: ${JSON.stringify(atob(s))}`);
  } catch (e) {
    console.log(`${label}: ${JSON.stringify(s)} → ${e.name}: ${e.message}`);
  }
}

token は、検証のために作った JWT の形の文字列です。署名の部分は本物ではありません。Node.js で実行した結果は次のとおりです。

text
Base64(正しい): "aGVsbG8=" → 結果: "hello"
Base64(= なし): "aGVsbG8" → 結果: "hello"
data URL のまま: "data:text/plain;base64,aGVsbG8=" → InvalidCharacterError: Invalid character
JWT のペイロード: "eyJzdWIiOiIxMjM0IiwibmFtZSI6IuOBreOBk-OBvuOCiyJ9" → InvalidCharacterError: Invalid character
エンコード前の文字列: "こんにちは" → InvalidCharacterError: Invalid character
途中で切れた Base64: "aGVsb" → InvalidCharacterError: The string to be decoded is not correctly encoded.

同じコードを Chromium のページの中で実行すると、メッセージは次のようになりました。

text
Base64(正しい): "aGVsbG8=" → 結果: "hello"
Base64(= なし): "aGVsbG8" → 結果: "hello"
data URL のまま: "data:text/plain;base64,aGVsbG8=" → InvalidCharacterError: Failed to execute 'atob' on 'Window': The string to be decoded is not correctly encoded.
JWT のペイロード: "eyJzdWIiOiIxMjM0IiwibmFtZSI6IuOBreOBk-OBvuOCiyJ9" → InvalidCharacterError: Failed to execute 'atob' on 'Window': The string to be decoded is not correctly encoded.
エンコード前の文字列: "こんにちは" → InvalidCharacterError: Failed to execute 'atob' on 'Window': The string to be decoded contains characters outside of the Latin1 range.
途中で切れた Base64: "aGVsb" → InvalidCharacterError: Failed to execute 'atob' on 'Window': The string to be decoded is not correctly encoded.

それぞれの原因は次のとおりです。

  • data URL のまま:data:text/plain;base64, の : や ; は Base64 の文字ではありません。Base64 の部分は , より後ろだけです。
  • JWT のペイロード:JWT の各部分は Base64URL で書かれています。MDN の Base64 の用語説明にあるとおり、Base64URL は URL に入れられるように、+ と / を - と _ に置き換え、末尾の = を省いたものです。HTML 標準の atob() の項によると、atob() は WHATWG の Infra 標準の forgiving-base64 decode で文字列を読みます。そこで読める文字は、末尾のパディングの = を除くと、英数字と +・/ だけです。- と _ は入っていません。
  • エンコード前の文字列:Base64 にする前の文字列を、そのまま渡しています。Chromium では、日本語のように Latin1 の範囲を超える文字があると、メッセージが「outside of the Latin1 range」になりました。
  • 途中で切れた Base64:Node.js では、このときだけメッセージが「not correctly encoded」になりました。同じ forgiving-base64 decode では、空白を除いた長さを 4 で割って 1 余る文字列は読めない、と決まっています。aGVsb は 5 文字なので、これに当たります。

一方、末尾の = がない aGVsbG8 は、Node.js でも Chromium でもエラーにならず、hello と読めました。= を補わなくても、atob() は読めます。

文字列を整えてから atob に渡す

data URL と Base64URL は、文字列を整えると読めるようになります。整える処理を関数にまとめました。

js
// Base64 と Base64URL のどちらでも読み、UTF-8 の文字列に戻す
export function decodeBase64(input) {
  let s = input.trim();
  // data URL なら、「,」より後ろだけを使う
  if (s.startsWith('data:')) s = s.slice(s.indexOf(',') + 1);
  // Base64URL の - と _ を、Base64 の + と / に戻す
  s = s.replace(/-/g, '+').replace(/_/g, '/');
  const binary = atob(s);
  const bytes = Uint8Array.from(binary, (c) => c.charCodeAt(0));
  return new TextDecoder().decode(bytes);
}

後半の Uint8Array.from() と TextDecoder は、日本語を文字化けさせないためのものです。MDN の atob() のページにあるとおり、atob() が返すのは、1文字が1バイトを表す文字列(バイナリ文字列)です。UTF-8 の日本語は1文字が複数のバイトになるので、そのままでは読めません。

- と _ を戻しただけで atob() の結果を出す場合と、decodeBase64() で読む場合を比べました。

js
import { decodeBase64 } from './decode.mjs';

const token = 'eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0IiwibmFtZSI6IuOBreOBk-OBvuOCiyJ9.c2lnbmF0dXJl';
const payload = token.split('.')[1];

// atob だけで直した場合(- と _ を戻しただけ)
console.log('atob のみ:', atob(payload.replace(/-/g, '+').replace(/_/g, '/')));

// decodeBase64 で読んだ場合
console.log('data URL:', decodeBase64('data:text/plain;base64,aGVsbG8='));
console.log('JWT のペイロード:', decodeBase64(payload));
console.log('名前:', JSON.parse(decodeBase64(payload)).name);
text
atob のみ: {"sub":"1234","name":"ã­ãã¾ã"}
data URL: hello
JWT のペイロード: {"sub":"1234","name":"ねこまる"}
名前: ねこまる

atob のみ の行は、画面に表示されない制御文字を含むため、見える文字だけを載せています。atob() だけの場合も、エラーは消えますが、名前の部分が文字化けしました。decodeBase64() では、エラーは出ず、日本語も正しく読めました。

Chromium のページの中で同じ関数を使っても、data URL: hello と JWT のペイロード: {"sub":"1234","name":"ねこまる"} が出ました。最初のページに、atob(dataUrl) を decodeBase64(dataUrl) に替えたボタンを足して押すと、エラーが出ずに画面に hello と表示されました。

注意

ブラウザーで JWT のペイロードを読めても、トークンが本物かどうかは分かりません。この関数は署名を検証していません。

Base64 でない文字列は、エラーを捕まえて扱う

こんにちは のように Base64 にしていない文字列や、aGVsb のように途中で切れた Base64 は、整えても読めません。入力欄に貼り付けられた文字列など、何が来るか分からないものを読むときは、エラーを捕まえて、読めなかったことを呼び出した側に返します。

js
import { decodeBase64 } from './decode.mjs';

// 入力された文字列を読み、読めなければ null を返す
function tryDecodeBase64(input) {
  try {
    return decodeBase64(input);
  } catch (e) {
    if (e instanceof DOMException && e.name === 'InvalidCharacterError') return null;
    throw e;
  }
}

for (const s of ['aGVsbG8=', 'こんにちは', 'aGVsb']) {
  console.log(JSON.stringify(s), '→', JSON.stringify(tryDecodeBase64(s)));
}
text
"aGVsbG8=" → "hello"
"こんにちは" → null
"aGVsb" → null

e.name で InvalidCharacterError だけを捕まえ、ほかのエラーはそのまま投げ直しています。読めなかったときに null を返すのか、画面にメッセージを出すのかは、使う場面に合わせて決めます。

Uint8Array.fromBase64 と Buffer.from を使う場合

atob() の代わりに、Uint8Array.fromBase64() を使う方法もあります。MDN のページには、alphabet: "base64url" を付けると Base64URL の - と _ を読めること、アルファベットの外の文字があると SyntaxError になることが書かれています。Chromium 153 では使えました。

js
const payload = 'eyJzdWIiOiIxMjM0IiwibmFtZSI6IuOBreOBk-OBvuOCiyJ9';
const bytes = Uint8Array.fromBase64(payload, { alphabet: 'base64url' });
console.log(new TextDecoder().decode(bytes));

結果は {"sub":"1234","name":"ねこまる"} でした。alphabet を付けずに同じ文字列を渡すと、InvalidCharacterError ではなく、次のエラーになりました。

text
SyntaxError: Found a character that cannot be part of a valid base64 string.

Node.js 22.23.4 では、typeof Uint8Array.fromBase64 が undefined で、まだ使えませんでした。

Node.js のコードでは、Node.js のドキュメントの buffer.atob() の項に、atob() は古い API なので Buffer.from(data, 'base64') を使うように、と書かれています。ただし、data URL、JWT のペイロード、こんにちは の3つを Buffer.from() に渡すと、どれもエラーにならず、間違った文字列は気づかないまま違う中身になりました。

text
"data:text/plain;base64,aGVsbG8=" → "u�Z��m��Z�vڱ�hello"
"eyJzdWIiOiIxMjM0IiwibmFtZSI6IuOBreOBk-OBvuOCiyJ9" → "{\"sub\":\"1234\",\"name\":\"ねこまる\"}"
"こんにちは" → "JF�"

Base64URL のペイロードは、Node.js のドキュメントの文字コードの説明にあるとおり 'base64' でも読めました。一方、data URL は先頭の部分まで読まれて前に意味のない文字が付き、こんにちは もエラーにならずに意味のない文字になりました。Buffer.from() に替えるときも、data URL の先頭の部分を外すことと、入力が Base64 かどうかを自分で確かめることは必要です。

​Posted by 86