kintoneカスタマイズJavaScriptが動かない時|エラーが出ない失敗の見分け方
kintoneのJavaScriptカスタマイズが動かないときは、コンソールの赤いエラー・黄色い警告・何も出ない、で疑う場所が分かれます。検証用環境で7通り試して確かめた、エラーの原文と見る所、値で見つける失敗をまとめました。
目次 クリックで開く
この記事の要点
- まず開発者ツールのコンソールを開き、赤いエラー・黄色い警告・エラーも警告も出ない・外部への通信の失敗、のどれかに分けます。当社の検証では、赤いエラーの場所の表示は kintone 本体のファイルで、自分のファイルの行は Stack trace の中にありました。
- 当社の検証で、エラーも警告も出なかった失敗は2つです。保存のイベントで Promise を返し忘れたもの(ログは 12000、保存された金額は 0)と、スマートフォン用の欄にファイルを置いていなかったものです。どちらも、保存された値と開いた画面を見て見つけました。差し替えた後に再読み込みしないと古いファイルのまま動くことも、コンソールの行に出る download.do の URL の引数(contentId)で気づきました。
- 公式の文書とお知らせを調べた範囲(2026年10月)では、kintone の CSP(読み込み先の制限)の告知も、許可ドメインの設定も見当たりません。当社の検証用環境では応答に CSP のヘッダーが無く、jsDelivr の URL 指定も読み込まれました。
コンソールで最初に分ける4つの症状(当社の検証で出たもの)
赤いエラー
Stack trace で自分の行までたどれた
出たもの
見る所:Stack trace の中の自分のファイルの行
黄色い警告
出たのは「登録は同期的に」の警告
出たもの
見る所:コンソールの表示に警告が入っているか
エラーも警告も出ない
ログの値と、保存された値・画面を比べた
出たもの
別に見たこと:再読み込みしないと古いファイルのまま(contentId で気づいた)
見る所:console.log の値と、保存された値・開いた画面
外部への通信
fetch では理由が読めなかった
出たもの
見る所:kintone.proxy に替えて試す
当社の検証の結果(環境と日付は「試した環境と、確かめ方」の節)
kintone の JavaScript カスタマイズが動かないときは、まずブラウザーの開発者ツールでコンソールを開き、出ているものが赤いエラーか、黄色い警告か、何も出ていないかで分けます。赤いエラーなら、自分のファイルの何行目かまでたどれます。厄介なのは残りの2つです。警告は、コンソールの表示をエラーだけに絞っていると見えません。エラーも警告も出ない失敗は、コードの誤りか置き方の誤りかを、症状から当たりをつけるしかありません。
当社は、kintone のプラグインを提供しながら、kintone の導入やカスタマイズも手伝っています。kintone の公式の文書とお知らせを調べた範囲では、CSP(ブラウザーが読み込み先を制限する仕組み)についての告知も、管理画面で許可するドメインを足す設定も見当たりませんでした。原因を公式の文書だけでは切り分けきれないので、検証用の kintone 環境でカスタマイズを壊したり書き方を変えたりして7通り試し、コンソールに何が出るかを確かめました。この記事はその記録と、公式の説明との突き合わせです。
扱うのは、アプリの[JavaScript / CSSでカスタマイズ]で入れたファイルが、ブラウザーで動かない場合です。プラグインの作り方、外部のシステムから REST API を呼ぶ連携、kintone のモバイルアプリは扱いません。
試した環境と、確かめ方
試したのは2026年10月13日の夜から14日の未明で、PC の Google Chrome を使いました。当社の検証用の kintone 環境(架空データ)に、検証用アプリを1つ作りました。フィールドは品名・数量・単価・金額・納期の5つ(フィールドコードは item、qty、unit_price、amount、due)で、レコードは2件です。この時期、エラーに出る kintone 本体のファイルのパスには 20261007 という数字が入っていました。公式の版番号ではありませんが、kintone の配信が変われば結果も変わりうるので、見比べるときの目印にしてください。
カスタマイズのファイルは、REST API でアプリの設定を書き換えて運用環境に反映しました。そのあと、別のタブでアプリを開き直してコンソールを読みました。試したのは原則1回ずつで、警告の件と Promise の件は測り直しています。アプリとレコードは全節で同じで、コードは症状ごとに書き替えました(詳細画面で納期までの日数を出す、保存のときに数量×単価を金額に入れる、など)。この記事の図と結果は、すべてこの環境・この時期のものです。
赤いエラー:場所の表示は kintone 本体、自分のファイルの行は Stack trace にあった
フィールドコードのつづり違い
詳細画面を開いたときに金額を読むコードで、フィールドコードの amount を amout とつづり違えました。詳細画面は普通に表示され、項目も値も出ます。利用者から見ると、何も起きていないのと区別がつきません。コンソールには次のエラーが出ていました。
コンソールの表示(詳細画面)
Uncaught TypeError: Cannot read properties of undefined (reading 'value')
- エラーの場所の表示:
static.cybozu.com/k/…/js/compiled/app/show.js:195:44 - Stack trace の1行目:
download.do?app=…&jsType=DESKTOP…:7:46
当社の検証では、エラーの右に出る場所の表示は kintone 本体の show.js で、自分のファイルは、エラーを開いた Stack trace の1行目に download.do?app=… の形で出ていました(7行目)。サイボウズのデバッグの記事(cybozu developer network「kintoneカスタマイズの基本的なデバッグの流れを身につけよう」、2025年7月8日更新)は、同じ種類のエラーで、エラーの1行目に出る自分のファイル名をクリックしてコードへ飛ぶ手順を紹介しています。当社の検証ではその位置が kintone 本体のファイルだったので、Stack trace まで開いて自分の行を探しました。
原因は「その名前のフィールドが無い」ことなので、コードのフィールドコードとアプリの設定を突き合わせます。同じ記事にある調べ方で、詳細画面を開いたままコンソールに kintone.app.record.get() と打つと、そのレコードの中身が返ります。コードで読んでいる名前がそこに無ければ、それが原因です。
ライブラリより先に実行した行
納期までの日数は、日付のライブラリ dayjs を jsDelivr の URL で読み込んで計算しました。設定画面で、自分の main.js を dayjs の URL より上に置いた(逆の順番にした)のが次の画面です。
kintone のヘルプは、複数のファイルは上から順番に読み込まれると書いています(kintone ヘルプ「JavaScriptやCSSでアプリをカスタマイズする」)。ところが、この逆の順番のままでも、詳細画面を開くイベントの中で dayjs を使うコードは動き、コンソールに [s1] 納期まで 17 日 と出ました。エラーになったのは、同じ逆の順番で、ファイルの先頭(イベントの外)で dayjs() を呼んだときです。
コンソールの表示(ファイルの先頭で dayjs() を呼んだ場合)
ReferenceError: dayjs is not defined
- 場所:
download.do?app=…&jsType=DESKTOP…:2:13
違いは、その行が実行される時期です。公式の説明では、ページを開くと、kintone の JavaScript API の初期化、カスタマイズのファイルの読み込み、kintone 本体による画面の初期化、の順に進みます(cybozu developer network「kintoneのイベントハンドラー登録の適切なタイミング」)。画面のイベントはカスタマイズのファイルを読み込んだ後に来るので、イベントの中で使うだけなら、ライブラリが後ろにあっても間に合います。読み込んだその場で実行される行だけが、並び順の影響を受けます。kintone の JavaScript API の初期化も、取り込んだファイルより前にあります。
ページを開いたときに進む順番
当社の検証では、ファイルの先頭で dayjs() を呼ぶ行はライブラリが下にあるとエラーになり、イベントの中のコードは逆順でも動いた
出典:cybozu developer network「kintoneのイベントハンドラー登録の適切なタイミング」(このあと DOMContentLoaded、load の順)、kintone ヘルプ
直すときは、ライブラリを上に置きます。ファイル名の左にある[ドラッグして並び替え]のアイコンで並びを変えられます。ライブラリをファイルの先頭で使う必要が無ければ、使う所をイベントの中に入れておくと、並び順に左右されません。
一覧画面の kintone.app.record.get():null のままではエラーにならない
一覧画面を開いたときのイベントで kintone.app.record.get() を呼び、戻り値をログに出すだけにすると、出たのは null で、エラーはありませんでした。
コンソールの表示(自分の console.log)
[s3] 一覧画面での kintone.app.record.get() = null
次に、同じイベントで戻り値から r.record.item.value のように値を読むと、はじめて赤いエラーになりました。
コンソールの表示(戻り値の中を読んだ場合)
Uncaught TypeError: Cannot read properties of null (reading 'record')
- エラーの場所の表示:
static.cybozu.com/k/…/js/compiled/app/index.js:171:367 - Stack trace の1行目:
download.do?app=…&jsType=DESKTOP…:3:37
つづり違いと同じく、場所の表示は kintone 本体の index.js で、自分のファイルは Stack trace の1行目でした。エラーが出たのは値を読んだ行で、原因は1つ前の、null が返った呼び出しのほうです。公式の説明では、PC でこの関数が使えるのはレコードの詳細・追加・編集・印刷の画面で、それ以外の画面で実行すると null が返ります。さらに、kintone.events.on() のイベントハンドラーの中では実行できません。ハンドラーの中では、引数のイベントオブジェクト(event.record)を使うよう書かれています。スマートフォン用の画面では kintone.mobile.app.record.get() という別の関数です(cybozu developer network「レコードの値を取得する」)。
黄色い警告:登録を1.5秒遅らせると、最初に開いた画面だけ動かなかった
設定を先に読み込んでからイベントを登録する作りを模して、kintone.events.on() の呼び出しを1.5秒遅らせました。再読み込みした直後の詳細画面では、そのハンドラーが動きません。赤いエラーは出ず、コンソールには次の警告が黄色で出ていました。
コンソールの表示(警告)
kintone.events.onによるapp.record.detail.showの登録は、同期的に行ってください。非同期に登録すると、イベントハンドラーが実行されない場合があります。 https://example.cybozu.com/k/redirect/ja-user-show-event
当社は1回目の測定でこの警告を読み落とし、「エラーは出ない」と記録していました。測り直して、警告が出ていたことを確かめています。コンソールの表示をエラーだけに絞っていると、同じように見落とします。
そのまま別のレコードへ移ると、遅れて登録したハンドラーは動きました。最初に開いた画面だけ動かず、2件目からは動くので、「たまに動かない」ように見えます。遅れを0ミリ秒(setTimeout の 0)にした版では、ハンドラーは動き、警告も出ませんでした。当社が試したのはこの2通りだけですが、警告文そのものも「実行されない場合があります」という言い方です。
公式の説明では、詳細・追加・編集の画面を表示するイベントは、カスタマイズのファイルが読み込まれた時点で同期的に登録する必要があります。DOMContentLoaded や load のイベントの中、jQuery で処理全体を DOMContentLoaded まで待たせる書き方の中、kintone.api() のコールバックの中で登録すると、画面のイベントが先に起きて、ハンドラーが呼ばれないことがあります。警告が出ていても、一見問題なく動く場合はあります。ただし、ネットワークの遅延やパソコンの性能、ほかのカスタマイズの影響で登録が大きく遅れ、トラブルの原因になることがある、とも書かれています(同じ記事)。この警告は、2018年7月の定期メンテナンスから出るようになりました(kintone API アップデート一覧)。
直すときは、ハンドラーの登録をファイルの先頭(即時関数の中でよい)で同期的に行い、設定の読み込みのような待ちが要る処理は、ハンドラーの中で行って Promise を返します。詳細画面を表示するイベントは、Promise を返すと完了を待つイベントの1つです(レコード詳細画面を表示した後のイベント)。次は、形を示す作例です(検証に使ったコードそのものではありません)。
作例
(() => {
'use strict';
// 登録はファイルの先頭で、同期的に
kintone.events.on('app.record.detail.show', (event) => {
// 待ちが要る処理はハンドラーの中で行い、Promise を返す
return loadSettings().then((settings) => {
// settings を使った処理
return event;
});
});
})();
エラーも警告も出ない:ログの値と、保存された値・開いた画面を比べる
コンソールにエラーも警告も出ないときは、コードの中に console.log を置いて、その値と、画面や保存後の値を比べます。当社の検証では、この形の失敗が2通りありました。あわせて、差し替えた後に再読み込みしないと古いファイルのまま動くことも確かめました。
保存のイベントで Promise を返していない
編集画面で保存するときのイベント(app.record.edit.submit)で、kintone.api() を呼んでから金額を event.record に入れる作りにし、その Promise を return し忘れました。前もってレコードの金額を0にしておき(数量10、単価1,200)、編集画面で保存しました。
コンソールの表示(自分の console.log)
[s6] 金額をセットした 12000
ログでは 12000 と正しく計算できています。それなのに、保存されたレコードの金額は0のままでした。保存そのものは行われ、レコードのリビジョンは上がっています。測り直した回も同じで、エラーも警告も出ませんでした。返していない Promise の中で event を書き換えても、kintone の保存はその前に終わっています。
Promise を return する形に直して同じ操作で保存すると、金額は12,000で保存されました。公式は、このイベントは Promise に対応していて、ハンドラーから Promise を return すると、非同期処理の完了を待ってからフォームの値に応じた制御ができる、と書いています(レコード編集画面で保存するときのイベント、イベントハンドラーを登録する)。サイボウズのデバッグの記事も、エラーが出ないときに確かめる点として、ハンドラーの中で return event; しているかを挙げています。
Promise を返し忘れた版と、返した版(同じ操作で保存)
返し忘れた版
ハンドラーは Promise を return していない
- コンソール:金額をセットした 12000
- 保存された金額:0(保存自体は行われた)
- エラーも警告も出ない
return した版
ハンドラーが kintone.api() の Promise を return する
- コンソール:金額をセットした 12000
- 保存された金額:12,000
当社の検証の結果(環境と日付は「試した環境と、確かめ方」の節)。数量10・単価1,200のレコードで、保存前の金額は0
作例(形を示すもので、検証に使ったコードそのものではありません)
// 作例:返し忘れ(ログは正しいが、保存された値に入らない)
kintone.events.on('app.record.edit.submit', (event) => {
const r = event.record;
const params = { app: kintone.app.getId(), id: event.recordId };
kintone.api(kintone.api.url('/k/v1/record', true), 'GET', params)
.then(() => {
r.amount.value = Number(r.qty.value) * Number(r.unit_price.value);
return event;
});
});
// 作例:直した形(Promise を return する)
kintone.events.on('app.record.edit.submit', (event) => {
const r = event.record;
const params = { app: kintone.app.getId(), id: event.recordId };
return kintone.api(kintone.api.url('/k/v1/record', true), 'GET', params)
.then(() => {
r.amount.value = Number(r.qty.value) * Number(r.unit_price.value);
return event;
});
});
スマートフォン用の欄にファイルを置いていない
ハンドラーには PC 用とスマートフォン用の両方のイベント名(app.record.detail.show と mobile.app.record.detail.show)を書き、ファイルは[PC用のJavaScript / CSSファイル]の欄にだけ置きました。PC の画面では [s7] 動いたイベント: app.record.detail.show と出ます。PC の Chrome でスマートフォン用の画面(URL に /k/m/ が入る画面)を開くと、コンソールには何も出ませんでした。エラーもありません。
同じファイルをスマートフォン用の欄にも置くと、スマートフォン用の画面で [s7b] 動いたイベント: mobile.app.record.detail.show と出ました。このとき、ファイルは jsType=MOBILE の URL で配られていました(PC 用の欄のファイルは jsType=DESKTOP)。kintone のヘルプは、カスタマイズを PC 用とスマートフォン用(スマートフォンアプリを含む)とで分けて設定すると書いています(kintone ヘルプ)。mobile. で始まるイベント名を書くだけでは足りず、ファイルもスマートフォン用の欄に置きます。
差し替えた後に、ページを再読み込みしていない
カスタマイズを差し替えたあと、開いていたタブでレコード1から2へ移っただけ(URL の #record= の部分だけが変わる移動)では、古いファイルのまま動いていました。気づいたのは、コンソールの各行に出どころとして表示される download.do の URL の引数 contentId が、差し替えた後も変わっていなかったからです。ページを再読み込みすると contentId が変わり、新しいファイルが配られました。直したのに変わらないときは、ページを再読み込みし、コンソールの行に出る download.do の URL の contentId が変わったかを見ると確かめられます。
公式に挙がっている、ほかの原因
サイボウズのデバッグの記事は、エラーが出ていないときに、カスタマイズが正しく適用されているか、kintone.events.on に書いたイベントの種類が間違っていないか、即時関数の書き方が正しいか、を確かめるよう書いています。また、スレッドの本文、スペースのお知らせ、ポータルのお知らせ掲示板に貼り付けたアプリには、カスタマイズが適用されません(kintone JavaScript API の共通仕様)。適用範囲を[アプリ管理者だけに適用]にしていれば、アプリ管理者でない人の画面では動きません。
エラーも警告も出ないときに確かめる順番
1
ページを再読み込みしたか
- 当社の検証では、レコードを移るだけでは古いファイルのままだった
- コンソールの行に出る download.do の URL の contentId で見分けた
2
置いた欄と適用範囲
- PC 用・スマートフォン用の両方に置いたか
- [適用しない][アプリ管理者だけに適用]になっていないか
- 貼り付けたアプリの画面ではないか
3
イベントの種類と返し方
- 画面に合ったイベント名か(スマートフォンは mobile. で始まる)
- 保存のイベントで Promise を return したか
- return event; しているか
出典:当社の検証の結果、cybozu developer network のデバッグの記事、kintone JavaScript API の共通仕様
外部への通信:fetch は理由が読めず、kintone.proxy は通った
カスタマイズから外部の URL(https://www.example.com/)へ、ブラウザーの fetch と kintone.proxy() の両方でリクエストを送りました。
コンソールの表示(自分の console.log)
[s5] fetch 失敗: Failed to fetch
[s5] kintone.proxy 成功 status= 200 本文の長さ= 577
fetch で JavaScript が受け取れたのは「Failed to fetch」だけでした。CORS(別のドメインへの通信をブラウザーが制限する仕組み)の詳しい理由はブラウザーのコンソールには出ますが、スクリプトからは読めません。エラーをどこかに書き残す仕組みを作っていても、理由までは残りません。
外部の URL へ送ったときの違い
fetch
ブラウザーから直接送る
- スクリプトが受け取ったのは Failed to fetch だけ
- 理由はブラウザーのコンソールの表示にしか出ない
kintone.proxy()
kintone の関数を通して送る
- status 200、本文の長さ 577 を受け取れた
- 本文は10MBまで、文字列だけ
- 自己証明書のサーバーとは通信できない
- 1日の API リクエスト数に数えない
当社の検証の結果(環境と日付は「試した環境と、確かめ方」の節)。制限は cybozu developer network「外部のAPIを実行する」、回数は kintone ヘルプ「制限値一覧」
kintone.proxy() は、公式に「クロスドメイン制約を回避」して外部の API へリクエストを送る関数と説明されています。引数は URL、メソッド、ヘッダー、送るデータの順で、コールバックを省くと Promise が返ります。レスポンスの本文は10MBまでで、文字列だけです。自己証明書を使ったサーバーとは通信できず、存在しないサーバーを指定するとステータス503(DNS Cache Missing)が返ります(cybozu developer network)。kintone.proxy() などで実行する外部の API は、1日の API リクエスト数に数えません。数えるのは、特定のアプリを指定する kintone の API だけです。上限は1アプリにつき1日、スタンダードコースで10,000件、ワイドコースで100,000件です(kintone ヘルプ「制限値一覧」、kintone REST API の共通仕様)。
それでも分からないとき:次に疑う所と、公式で確かめられること
ここまでの症状に当たらないときに、次に疑う所を公式の文書で確かめられる範囲でまとめます。当社の検証で試していないものは、公式の記載だけをもとに書いています。
| 疑う所 | 公式で確かめられること |
|---|---|
| kintone の REST API のエラー | 失敗すると200番台以外のステータスと、id・code・message を持つ JSON が返る(共通仕様)。デバッグの記事の例では、コンソールに POST …/k/v1/record.json 403(Forbidden) と出て、message は「権限がありません」(書き込み先アプリのアクセス権に「レコード追加」が無かった)。フィールドコードの大文字・小文字の違いでは 400 で「入力内容が正しくありません」(デバッグの記事)。同時アクセスが1ドメインにつき100を超えると 429(制限値一覧)。エラーコードの一覧表は、公式の文書には見当たらない |
| APIトークン | アプリ・レコード・フィールドのアクセス権の設定に関わらず、トークンに付けたアクセス権が優先される。ライトコースでは使えない。生成したトークンは第三者に知られないようにする(kintone ヘルプ)。カスタマイズのファイルの中身は開発者ツールのソースの画面で読める(デバッグの記事)ので、トークンはファイルに書き込まないほうがよい。権限が足りないときのステータスとメッセージは、公式の文書では確かめられなかった(当社で確かめたらここに足す) |
| CSP | 2026年10月13日に cybozu developer network・kintone ヘルプ・アップデート情報・お知らせを調べた範囲では、告知も、許可するドメインを足す設定も見当たらない。[kintoneシステム管理]の項目(ヘルプ)にも、[JavaScript / CSSでカスタマイズ]の画面にも欄は無い。URL 指定には cybozu.com 以外のドメインも指定できる(ヘルプ)。当社の検証用環境では、アプリの画面の応答に CSP のヘッダーも Report-Only のヘッダーも無かった(今後も同じとは言えない) |
| 何も変えていないのに動かなくなった | 画面の要素の id や class 属性の値は予告なく変わり、DOM の構造も変わることがある。DOM を操作するなら kintone の JavaScript API を使う(コーディングガイドライン)。画面の部品を直接つかんでいるコードから疑う |
| ほかのカスタマイズとの干渉 | グローバル変数を避け、即時関数やブロックの中で変数を定義する(同)。kintone 全体のカスタマイズはアプリの個別の設定より先に読み込まれる(ヘルプ) |
| カスタマイズが原因かの切り分け | 適用範囲を[適用しない]にすると止められる。変更には kintone のシステム管理権限が要る。カスタマイズの内容はサイボウズのサポートの対象外で、相談先はプラグインの提供元か自社のシステム開発者(ヘルプ) |
| 直したファイルの入れ方 | 適用できるのは kintone のシステム管理者だけで、すべてのユーザーに適用する前に[アプリ管理者だけに適用]で確かめるよう勧められている(ヘルプ)。コマンドで反映するなら、2026年2月8日から、cli-kintone の customize init/apply/export が使える(お知らせ)。customize-uploader は「非推奨」で、2026年8月版の定期メンテナンスでメンテナンスを終了する、今後は cli-kintone を使うように、と書かれている(cybozu developer network) |
直したら、保存された値とスマートフォンの画面まで見る
直したあとは、コンソールにエラーが無いことだけで終わりにせず、保存されたレコードの値と、スマートフォン用の画面まで開いて確かめてください。
日付の計算や金額の集計のように、コードを書いて保守しなくても済む処理なら、当社の kintone プラグインで足りるかもしれません。
kintone でどんな業務アプリを作れるかは、当社の動画でも紹介しています。
公式の記載は、2026年10月13〜14日に cybozu developer network と kintone ヘルプで確かめたものです。
kintone 導入支援
何から作ればいいか分からない、標準機能では業務にはまらない、Salesforce や Excel・会計ソフトと二重管理になっている。kintone のアプリの全体設計から、プラグイン・API での連携、社内で作れる状態までを支援します。




