Tips

kintoneカスタマイズの基本的なデバッグの流れを身につけよう

著者名：江﨑 全英（ サイボウズ株式会社 (External link) ）

目次

はじめに

固定リンクがコピーされました

kintoneカスタマイズのデバッグ、できていますか？
「はじめようシリーズのカスタマイズはできたけど、自分で実装するとカスタマイズがうまく動作しなくてどこをどう修正したらいいか分からない」という声を聞くことがあります。
"脱はじめようシリーズ"を目指すみなさんに向けて、本記事ではkintoneカスタマイズの基本的なデバッグの流れを紹介します。

kintoneカスタマイズのデバッグについては、 動かない？そんな時はデバッグをしてみよう！入門編 も合わせて目を通してみてください。
デバッグの流れはさまざまな原因によって異なるため、本記事で紹介しているエラー対処の流れがあらゆるパターンに当てはまるわけではありません。

カスタマイズのデバッグにはGoogle Chrome（バージョン：138.0.7204.93）を利用しています。

基本的なデバッグの流れ

固定リンクがコピーされました

kintoneカスタマイズの基本的なデバッグの流れは次のとおりです。

  1. カスタマイズを適用して、開発者ツールのコンソール画面（以下、コンソール画面）を開く。
  2. コンソール画面を開いて、エラーが出ているか確認する。
  3. エラーが出ている場合、エラーの内容から原因調査をする。
  4. エラーが出ていない場合、起きている現象から原因調査をする。

この流れに沿ってカスタマイズが動作しない原因を探しにいきましょう。

1. カスタマイズを適用して、コンソール画面を開く

固定リンクがコピーされました

カスタマイズを適用した後に意図した動作ができていない場合は、まずコンソール画面を開きましょう。
Google Chromeのコンソール画面は、次の操作で開くことができます。

  • Google Chrome：Ctrl + Shift + Jキーを同時に押下（MacはCommand + Option + J）

その他ブラウザーのコンソール画面の開き方については、次の操作で開くことができます。

  • Firefox：Ctrl + Shift + Kキーを同時に押下（MacはCommand + Option + K）

  • Microsoft Edge：Ctrl + Shift + Jキーを同時に押下（MacはCommand + Option + J）

2. コンソール画面を開いて、エラーが出ているか確認する

固定リンクがコピーされました

次に、コンソール画面にエラーが出ている時は、エラーの内容を読み取ってその原因を調査します。
一方、コンソール画面にエラーが出ていない時は、発生している現象の内容を基にうまく動作しない原因を調査します。

本記事では、3つのエラーパターンでデバッグの流れの例を紹介しているので、気になるエラーパターンを確認してみてください。

3. エラーが出ている場合、エラーの内容から原因調査をする

固定リンクがコピーされました

コンソール画面に出力されているエラーの内容をもとに次のいずれか、もしくは複数の方法を組み合わせて調査します。
各調査方法の具体的なやり方についてはリンク先を参照してください。

4. エラーが出ていない場合、起きている現象から原因調査をする

固定リンクがコピーされました

コンソール画面にエラーが出力されていない場合は、起きている現象を把握したうえで、主に次をチェックします。

  • カスタマイズが正しく適用されているか。
  • kintone.events.onでセットしたイベントタイプが間違っていないか。
  • 即時関数の記述が正しく行われているか。

上記以外にも「kintone.events.onのイベントハンドラー内で、return event;しているか」など、ケースに応じてさまざまなチェックポイントが考えられます。
ここで挙げたチェックポイントを確認しても正常に動作しない場合は、他に何か間違っている点があるかもしれません。
根気強く、考えつく限りの可能性をチェックしてみる必要があります。

よくあるエラー

固定リンクがコピーされました

1. 'Cannot read property 'value' of undefined' エラーの場合

固定リンクがコピーされました

実現したいカスタマイズ

アプリストアにある「案件管理」アプリをカスタマイズして、会社名というフィールド名のフィールドの値をアラートで出力したい。

適用したカスタマイズ
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

/*
 * sample program
 * Copyright (c) 2025 Cybozu
 *
 * Licensed under the MIT License
 * https://opensource.org/license/mit/
 */
(() => {
  'use strict';
  const companyNameTxt = '会社名';

  kintone.events.on('app.record.detail.show', (event) => {
    const record = event.record;
    alert(record[companyNameTxt].value);
    return event;
  });
})();
コンソール画面

エラーの内容は次のとおりです。

1

Uncaught TypeError: Cannot read properties of undefined(reading 'value')

デバッグの流れ

コンソール画面に表示されるエラーを確認すると、valueがundefinedになっていることを確認できます。
ここでは、valueがundefinedになっている原因調査のため、カスタマイズのコードを確認します。

開発者ツールのソースタブから、適用したカスタマイズの中身を確認できます。
コンソール画面に出力されているエラーの1行目test.js:14をクリックすると、エラーが発生したコードに直接遷移できます。

コンソール画面に出力されているエラー内容とカスタマイズ内容を照らし合わせると、valueの記載があるのは14行目だけです。
そのため、14行目に何か問題がありそうだと見当をつけることができます。

さらに、14行目のvalueは変数recordの中の「会社名」というフィールドコードのフィールドの値（value）です。
上記の理由から、次の2点が原因として考えられると推測しました。

  • 変数recordの中身がない。
  • 「会社名」というフィールドコードのフィールドが存在しない。

ここからは次の4パターンの調査方法のいずれかを利用して、原因調査を進めます。

  • A. ブレイクポイント機能を利用して、調査する方法
  • B. console.log(record);をコードに入れて調査する方法
  • C. kintone.app.record.get();をコンソール画面に入力して調査する方法
  • D. debugger;をコードに入れて調査する方法
A. ブレイクポイント機能を利用して、調査する方法

開発者ツールのソースタブでブレイクポイント機能を使うと、カスタマイズの読み込みを好きなところで一時的に停止できます。
また、コード中の変数をマウスオーバーすることで、変数の中に何が格納されているかを確認できます。

そこで、この機能を使って次のGIFのように14行目にブレイクポイントを入れて再度読み込みます。
読み込んだら、変数recordをマウスオーバーしrecordの中身を確認します。
なお、ブレイクポイントは複数ヵ所設定できるので、変数が複数存在するカスタマイズでは、怪しいと思われるすべての行にブレイクポイントを入れて1箇所ずつ確認します。

上のGIFから、変数recordの中身はあるもののrecordの中に「会社名」というフィールドコードのフィールドは存在しないことが分かります。
そこで、アプリ管理のフォーム設定画面を確認すると、会社名フィールドのフィールドコードは「文字列1行」だと判明しました。

そのため、カスタマイズ10行目の「会社名」の記述を「文字列1行」に書き換える必要があります。
コードを書き換えて再度レコードの詳細画面を開いてみると、想定どおりアラート画面が表示されており無事に意図した動作を確認できました。

B. console.log(record);をコードに入れて調査する方法

「変数recordの中身がない」もしくは「会社名というフィールドコードのフィールドが存在しない」かどうかを確認するために、カスタマイズの14行目にconsole.log(record);を挿入して実行してみます。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

/*
 * sample program
 * Copyright (c) 2025 Cybozu
 *
 * Licensed under the MIT License
 * https://opensource.org/license/mit/
*/
(() => {
  'use strict';
  const companyNameTxt = '会社名';

  kintone.events.on('app.record.detail.show', (event) => {
    const record = event.record;
    console.log(record);
    alert(record[companyNameTxt].value);
    return event;
  });
})();

このカスタマイズを実行し、コンソールタブを確認します。
コンソール画面にはさきほどのエラーと一緒に、変数recordの中身が出力されているのを確認できます。

コンソール画面に出力されている変数recordの中身を確認すると、recordの中に「会社名」というフィールドは存在しないことが分かります。
そのため、会社名フィールドのフィールドコードが間違っていると推測できます。
あとは、Aと同じ流れです。

C. kintone.app.record.get();をコンソール画面に入力して調査する方法

「変数recordの中身がない」もしくは「会社名というフィールドコードのフィールドが存在しない」かどうかを確認します。
開発者ツールのコンソールタブでkintone.app.record.get();を実行して、recordの中身を確認します。

具体的な使い方のイメージは、 Google Chrome開発者ツールのTips集 -kintone開発特化編- で詳しく解説しています。

コンソール画面で実行すると、Bと同様にrecordの中身を確認できます。
ぜひご自身で確認してみてください。

D. debugger;をコードに入れて調査する方法

カスタマイズの実行を任意の場所で停止する方法として、Aで紹介したブレイクポイントを使う方法以外にもコードの中にdebugger;を入れる方法があります。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

/*
 * sample program
 * Copyright (c) 2025 Cybozu
 *
 * Licensed under the MIT License
 * https://opensource.org/license/mit/
*/
(() =>{
  'use strict';
  const companyNameTxt = '会社名';

  kintone.events.on('app.record.detail.show', (event) => {
    const record = event.record;
    debugger;
    alert(record[companyNameTxt].value);
    return event;
  });
})();

上のように14行目にdebugger;と記述したコードをkintoneに読み込ませて実行すると、debugger;の記述があるところでカスタマイズの実行を停止できます。

debuggerの詳細については debugger（外部サイト） (External link) を参照ください。

2. 'POST {URL} 403 （Forbidden）' エラーの場合

固定リンクがコピーされました

実現したいカスタマイズ

「案件管理」アプリのレコードを閲覧したユーザーの閲覧ログを「閲覧履歴」アプリにレコードとして残したい。

適用したカスタマイズ
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

/*
 * sample program
 * Copyright (c) 2025 Cybozu
 *
 * Licensed under the MIT License
 * https://opensource.org/license/mit/
*/
(() => {
  'use strict';

  kintone.events.on('app.record.detail.show', async (event) => {
    try {
      const CONTACT_APP_ID = 408;
      const APP_ID = event.appId;
      const RECORD_ID = event.recordId;
      const params = {
        app: CONTACT_APP_ID,
        record: {
          閲覧アプリid: {
            value: APP_ID
          },
          閲覧レコード番号: {
            value: RECORD_ID
          }
        }
      };

      const resp = await kintone.api(
        kintone.api.url('/k/v1/record', true), // - pathOrUrl
        'POST', // - method
        params, // - params
      );
      console.log('成功');
    } catch (error) {
      console.log('失敗');
    }
    return event;
  });
})();
コンソール画面

エラーの内容は次のとおりです。

1

POST https://sample.cybozu.com/k/v1/record.json 403(Forbidden)

デバッグの流れ

コンソール画面を見ると、次の2点を確認できます。

  • record.jsonのPOSTリクエストがエラーコード403で出力されていること
  • カスタマイズ35行目に記載しているconsole.log('失敗');が出力されていること

ひとまずconsole.log('成功');とconsole.log('失敗');それぞれの1行下に、console.log(resp);とconsole.log(error);を追記してrespもしくはerrorの中身を確認します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

/*
 * sample program
 * Copyright (c) 2025 Cybozu
 *
 * Licensed under the MIT License
 * https://opensource.org/license/mit/
*/
(() => {
  'use strict';

  kintone.events.on('app.record.detail.show', async (event) => {
    try {
      const CONTACT_APP_ID = 408;
      const APP_ID = event.appId;
      const RECORD_ID = event.recordId;
      const params = {
        app: CONTACT_APP_ID,
        record: {
          閲覧アプリid: {
            value: APP_ID
          },
          閲覧レコード番号: {
            value: RECORD_ID
          }
        }
      };

      const resp = await kintone.api(
        kintone.api.url('/k/v1/record', true), // - pathOrUrl
        'POST', // - method
        params, // - params
      );
      console.log('成功');
      console.log(resp);
    } catch (error) {
      console.log('失敗');
      console.log(error);
    }
    return event;
  });
})();

追記して再度読み込んでみると、コンソール画面にerrorの内容が出力されます。

messageに「権限がありません」と出力されるので、POST先アプリのアクセス権設定を確認します。

「閲覧履歴」アプリのアクセス権を確認したところ、アプリのアクセス権で「レコード追加」が設定されていないとわかります。
そこで、レコード追加にチェックを入れて保存します。

再度読み込んで実行すると、まだうまく動作していないようです。
次のエラーがコンソール画面に出力されています。

1

POST https://sample.cybozu.com/k/v1/record.json 400(Bad Request)

messageに「入力内容が正しくありません」とあるので、errorsの中を見てみます。
record.閲覧アプリID.valueのmessagesが「必須です」と出力されています。

つまり、フィールドコード「閲覧アプリID」の値（value）をPOSTリクエストのbodyに正しくセットできていないことがわかります。
そこでカスタマイズの内容と「閲覧アプリID」フィールドのフィールドコードを再度確認します。
カスタマイズが正しいフィールドコードになっていないことがわかったので、アプリの設定に合わせて「閲覧アプリID」に修正します。

  • カスタマイズに記載した「閲覧アプリID」フィールドのフィールドコード：閲覧アプリid
  • アプリに設定した「閲覧アプリID」フィールドのフィールドコード：閲覧アプリID

再度読み込むと閲覧ログが「閲覧履歴」アプリに登録され、意図した動作を確認できました。

3. コンソール画面にエラーが出ていない場合

固定リンクがコピーされました

実現したいカスタマイズ

「案件管理」アプリのレコードを閲覧したユーザーの閲覧ログを「閲覧履歴」アプリにレコードとして残したい。
2. 'POST {URL} 403 (Forbidden)' エラーの場合 と同じカスタマイズです。

適用したカスタマイズ
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

/*
 * sample program
 * Copyright (c) 2025 Cybozu
 *
 * Licensed under the MIT License
 * https://opensource.org/license/mit/
*/
(() => {
  'use strict';

  kintone.events.on('app.record.detail.show', async (event) => {
    try {
      const CONTACT_APP_ID = 408;
      const APP_ID = event.appId;
      const RECORD_ID = event.recordId;
      const params = {
        app: CONTACT_APP_ID,
        record: {
          閲覧アプリID: {
            value: APP_ID
          },
          閲覧レコード番号: {
            value: RECORD_ID
          }
        }
      };

      const resp = await kintone.api(
        kintone.api.url('/k/v1/record', true), // - pathOrUrl
        'POST', // - method
        params, // - params
      );
      console.log('成功');
    } catch (error) {
      console.log('失敗');
    }
    return event;
  });
});
コンソール画面

出力なし

デバッグの流れ

このカスタマイズを適用しても、「閲覧履歴」アプリにレコードが追加されておらずコンソール画面にも何も出力されていません。
開発者ツールのソースタブで、カスタマイズが適用されているか確認してみると、カスタマイズは適用されているようです。

カスタマイズは適用されているようなので、カスタマイズが実行されているかを確認するためにブレイクポイントをセットします。
再度読み込みしてみたところ、なぜかブレイクポイントで処理が止まりません。

このことから、何らかの原因でカスタマイズが実行されていないと推測されます。
原因の可能性として次の2点を考えました。

  • kintone.events.onでセットしたイベントタイプが間違っていないか。
  • 即時関数の書き方ができているか。

それぞれを確かめてみます。
kintone.events.onのイベントではレコード詳細画面の表示後イベントを実行してほしいので、 レコード詳細画面の表示後イベント のapp.record.detail.showを設定します。
カスタマイズを確認すると同じイベントタイプが記載されているので、イベントタイプは問題なさそうです。

では、次に正しい即時関数の書き方になっているか確認してみます。
サンプルコードを確認すると、()が抜けています。

39行目に次のように()をつけることで、意図した動作を確認できました。

最初に適用したカスタマイズをよく確認すると、次のような形になっています。

1
2
3

(() => {
  // 処理内容
}); // ()が必要

この書き方は即時関数の書き方になっておらず、再読み込みしてもカスタマイズは実行されません。
そのため、ブレイクポイントをセットしても処理が止まりませんでした。

即時関数について詳しく知りたい方は IIFE(即時実行関数式)（外部サイト） (External link) を参照してください。

まとめ

固定リンクがコピーされました

カスタマイズが動作しない原因はさまざまです。
実際のデバッグケースは、この記事で取り上げた内容より複雑でエラーの原因を探し出すのはたいへんだと思います。

しかし、この記事で紹介したデバッグの流れや考え方を参考にトライアンドエラーを繰り返していけば、少しずつエラー原因へ近付けるようになるはずです。
ぜひ、この記事に書いている方法や考え方を身につけてデバッグ力を磨いてください！

Google Chromeの開発者ツールを利用したJavaScriptカスタマイズのデバッグ方法についてもっと知りたい方は、公式サイト DevTools（外部サイト） (External link) の記事も参考にしてみてください。

information

このTipsは、2025年6月版kintoneで動作を確認しています。