Reference, glossary, and troubleshooting
Find the right Apps Script term, service reference, example, or troubleshooting guide when maintaining a production script.
By the end
Locate a precise source for a service, execution surface, error, or example instead of relying on a copied fragment.
Use this appendix to look up Apps Script terms, common errors, book examples, and reference documentation. Google's official documentation is the authority for current APIs, quotas, deployment settings, and product policies.
Glossary
| Term | Meaning | Where to go next |
|---|---|---|
| Access token | A short-lived bearer credential sent to a resource API. Local token presence does not prove that the provider still accepts it. | Access and refresh lifetimes |
| Advanced service | An Apps Script service that exposes a Google API. Enable it in Apps Script. If the script uses a standard Cloud project, also enable the Google API in that Cloud project. | Advanced services |
| Argument and parameter | An argument is a value supplied by a call; a parameter is the local name receiving that value inside the function. | Functions and calls |
| Array | An ordered collection accessed by zero-based indexes. A range's getValues() result is an array of row arrays, not a live connection to the cells. | JavaScript arrays |
| Authentication | Establishing the identity of a caller. It is separate from deciding what that caller may do. | Consent and remote authentication |
| Authorization | Deciding which operations an identity may perform. OAuth scopes do not replace provider roles, resource permissions, or organization policy. | Separate grants and resource access |
| Bound script | A project attached to one Sheets, Docs, Slides, or Forms file. | Bound versus standalone scripts |
| Cache | Disposable stored data that can be recomputed. A requested expiration does not guarantee that the value remains available until then. | Rebuild a cached summary |
| Callback | A function passed to another function to be called as part of its work. An array callback runs in the current execution; it is not a trigger or a new execution. | Array transformations |
| Chart builder | A changeable description used to construct a chart. build() produces an object; inserting or updating that object is a separate Sheets operation. | Building versus saving a chart |
| Checkpoint | Persisted progress used to decide what work to inspect or attempt next. A checkpoint does not make a separate service action transactional or exactly-once. | Local plans and external checkpoints |
| Coercion | Automatic conversion between value types. Strict comparison avoids some implicit conversions, while explicit conversion still needs validation. | Values and objects |
| Content-Type | Response metadata describing the body's format. It differs from an Accept request preference; valid JSON still needs shape and value checks. | Check responses in stages |
| Custom function | A spreadsheet formula function written in Apps Script that returns a value to a cell without changing other cells or using authorized services. | Custom functions |
| Data validation | Rules that restrict what a user can enter into a spreadsheet cell. Script-written validation can preserve or replace manual rules. | Sheets validation and formatting |
| Deployment | A released configuration of a script, such as a web app or add-on. | Deployments |
| Diagnostic | A code checker warning or error that identifies mistakes before or during script execution. | Find mistakes with diagnostics |
| Endpoint | The API address and operation a client intends to call. Its provider defines input, identity, response and delivery contracts. | Describe an HTTP request |
| Execution | One invocation of script code, with its own local variables, identity and limits. A later execution does not recover an earlier local variable automatically. | State across runs |
| Execution identity | The user whose authority applies to one execution. It depends on the surface, such as editor, trigger, or web app. | Authorization guide |
| Form-submit event | The event supplied to an installed submission handler. A Forms event contains a FormResponse; a linked-Sheets event has a different shape. | Actual Forms events |
| HMAC | A message-authentication code computed from agreed bytes and a shared key. It authenticates those bytes but does not encrypt the body. | Authenticated event fields |
| Installable trigger | A trigger created by a user that runs under that creator's account. | Safe triggers |
| Instant | A point on the timeline represented by a JavaScript Date. Display time zones change its representation, not the stored instant; an all-day calendar date has a different meaning. | Calendar dates and instants |
| JSON | A text format for data. Parsing reconstructs a value; it does not prove the value's expected fields, types or business meaning. | Response parsing and validation |
| Library | Another Apps Script project included by Script ID and version number. The consumer project must have read access to the library script. | Producer and consumer projects |
| Lock | Coordination among participating executions within a defined scope. Acquire it before reading the state used for an update; it does not lock other services or human edits. | Protect read-modify-write |
| Manifest | appsscript.json, the project configuration file for runtime settings and explicit scopes. | Manifests |
| Nullish value | null or undefined. Zero, false and an empty string are not nullish; using truthiness as a defaulting rule can discard those meaningful values. | Values and missing data |
| Object and property | An object groups named values. A property is one of those named entries; changing a shared object's property can be visible through another reference to the same object. | Values and objects |
| OAuth callback URI | The registered address to which the provider returns the browser after authorization. The OAuth2 library's Apps Script /usercallback URI is not a web-app /exec URL. | Register the exact callback |
| OAuth grant | Provider authorization for a client to act with specified permissions. It is separate from Apps Script's own consent and does not share a file with the authorizing account. | Two authorizations |
| OAuth scope | A named permission, such as access to spreadsheets or external requests. | Authorization scopes |
| Pagination | Reading portions of a larger result through the provider's page contract. Reaching a local page or item limit does not establish that every record was read. | Bounded public pagination |
| Properties service | String-valued persistence scoped to a script, executing user or eligible document context. Reading a property does not create a live, automatically saved object. | Choose a property store |
| Pure helper | A function whose return value depends only on its parameters and that performs no service calls or state mutations. | Functions and decisions |
| Quota | A limit on a service or account use, often measured over time. | Current quotas |
| Range | A selected rectangle of spreadsheet cells. Its two-dimensional values must match the dimensions supplied to setValues(). | Batched Sheets work |
| Reconciliation | Checking recorded state and target resources after an interrupted write to determine whether the operation succeeded before retrying. | Calendar create recovery |
| Refresh token | A longer-lived credential used to request another access token without a new consent round trip. It can expire or be revoked; a saved value is not a permanent connection. | Observe actual refresh behavior |
| Schema and revision | A schema defines data shape and invariants. A format version identifies how to interpret stored data; a revision identifies a state update within that format. | Versioned state records |
| Scope, lexical | The region of code where a variable name is available. It is unrelated to an OAuth scope or a Properties sharing scope. | Functions and scope |
| Script ID | The identifier of an Apps Script project, shown in Project Settings. | clasp guide |
| Simple trigger | A reserved function such as onOpen that runs under simple-trigger restrictions. | Triggers explained |
| Smoke test | A fast integration test run against real services or a staging tab to verify that basic operations succeed before production use. | Test Apps Script code |
| Standalone script | A project not attached to a container file. | Bound versus standalone scripts |
| Strict comparison | === and !== compare without first converting one operand to the other's type. Object equality compares identity, not matching fields. | Values and comparison |
| Structured output | Model responses constrained to a strict JSON schema so that values can be parsed and validated reliably by script code. | Use AI models from Apps Script |
| Trigger | An event-driven execution, such as opening a file or a schedule. | Triggers guide |
| UrlFetchApp | The Apps Script service for HTTP and HTTPS requests. | HTTP response reference |
| Version | A numbered, immutable snapshot of Apps Script project source. Saved Head, a deployment, and the version selected by a library consumer are different things. | Numbered library releases |
| Web app | A deployed doGet or doPost endpoint that returns HTML or text. | Web apps |
| Webhook | An event delivered by HTTP POST to a receiver endpoint whose authentication, status-code, and retry behavior must match the sender's contract. | Choose a supported delivery contract |
| iCalUID | The CalendarApp event identifier returned by CalendarEvent.getId(). It is not interchangeable with Calendar REST event.id; retain the calendar context as well. | Stored Calendar identities |
Troubleshooting index
Start with the exact error, execution type, and time. The Apps Script dashboard can show project executions and health data, but its visibility depends on your access to the project.
| Symptom | First check | Likely next action |
|---|---|---|
Authorization is required | The execution identity and the current manifest scopes. | Run the authorized setup flow as the relevant user. A background trigger cannot prompt for a missing permission. |
Cannot call ... of null or a missing sheet error | The file, sheet name, and selected range used by the code. | Stop with a descriptive check before reading or writing. See common errors. |
Service invoked too many times or a limit error | The current quota page and how often the code calls the service. | Batch operations, reduce frequency, and checkpoint work. Do not guess a wait period from an old blog post. |
| A menu does not appear | That the project is bound to the file, saved, and has an exact onOpen function. | Reload the file. See custom menus. |
| A trigger worked for one person but not another | Who created the installable trigger and what they authorized. | Review trigger ownership and recreate it under the intended owner if appropriate. |
| A web app reaches the wrong data | The deployment's execution identity and audience. | Review the deployment configuration and test in an approved isolated project. |
| An HTTP integration fails | The status code, provider's documented response, and redacted request metadata. | Do not retry a write until you know whether the remote system received it. See Fetch data from web APIs. |
| A local change differs after upload | Emitted source, manifest, runtime, and target Script ID. | Inspect the upload configuration and execution log. See Develop Apps Script locally. |
| The saved state no longer parses or has an unsupported version | The exact property key, stored format and source version. | Preserve the original value before inspection; do not silently initialize over it. See recovering a bad record. |
| A cache entry disappeared | Whether the result can be recomputed from authoritative data. | Rebuild the result; do not treat a cache miss as missing business state. |
| A paginated read stops with only some records | The page/item limits, provider next link and reported partial state. | Retain the distinction between an accepted partial sample and a complete traversal; inspect failures before repeating requests. |
| An output ID is missing after a create error | The saved intent, exact target and any recovery marker. | Treat the result as uncertain. A null lookup, empty search or local error does not by itself authorize another create. |
TypeError: X is not a function | The receiver's class and the exact method name. | Check the name against the declared methods for that class. See TypeError: X is not a function and choose the right service call. |
Cannot read properties of null (reading 'getRange') | The sheet lookup one line earlier. | Guard the nullable result before dereferencing it. See Cannot read properties of null and JavaScript arrays. |
TypeError: e.range is not a function | Whether range is a property of the event object. | Drop the call parentheses; the property is already a Range. See TypeError: e.range is not a function and trigger event objects. |
Cannot read properties of undefined (reading 'setDataValidation') | The index or lookup that produced the range. | Fix the out-of-range index or the lookup that returned nothing. See Cannot read properties of undefined. |
The number of columns in the data does not match the number of columns in the range | Every row of the 2D array has the same length. | Pad or trim the ragged row, then size the range from the data. See column count mismatch and JavaScript arrays. |
The number of rows in the data does not match the number of rows in the range | The outer array length against the range height. | Size the range from values.length instead of a separate count. See row count mismatch and batching writes. |
The coordinates or dimensions of the range are invalid | Zero or negative rows, columns, or sizes in the getRange call. | Guard empty results and remember coordinates are one-based. See invalid range dimensions and batching writes. |
ReferenceError: X is not defined | Spelling, scope, and whether every project file saved. | Fix the typo or move eager top-level code into functions. See ReferenceError: X is not defined and functions and calls. |
ReferenceError: GoogleAppsScript is not defined | Any use of the type namespace in a value position. | Use the service globals at runtime; keep GoogleAppsScript.* in type positions. See GoogleAppsScript is not defined and TypeScript builds. |
Missing ) after argument list | Unclosed parentheses in nested calls above the reported line. | Close the delimiter the parser flagged; check the opening line, not only the reported one. See Missing ) after argument list and debug executions. |
Unterminated string literal | Missing quotes and non-ASCII quotes pasted from documents. | Close the string or use a template literal for multiline text. See Unterminated string literal. |
JSON.parse errors such as Unexpected token | Whether the argument is a string, and what the endpoint actually returned. | Parse response.getContentText() and check for an empty, incomplete or non-JSON body. See JSON.parse errors and connect services. |
Follow this book's redaction policy: do not paste production tokens, private rows, or unredacted HTTP bodies into a support request or public issue. The Apps Script logging guide explains its privacy protections. A useful report names the execution time, surface, safe reproduction input, error text, and the smallest code path involved.
Example catalog
The book examples are runnable projects or read-only previews. Each linked chapter gives setup, expected results, side effects, and cleanup instructions.
| Example | What it demonstrates | Effects |
|---|---|---|
| First Sheets script | Reading a supplied Sheets input. | Reads the supplied customer rows; does not write data. |
| Values and objects | Values, objects, and pure calculations before service workflows. | Changes in-memory fictional data and writes execution-log messages. |
| Functions and decisions | Named helpers, pure functions, and control flow. | Runs in-memory request-routing helpers and writes execution logs. |
| JavaScript arrays | Transforming, filtering, and mapping row collections. | Processes in-memory request arrays without modifying external data. |
| Batch request statuses | Reading and updating rectangular Sheet ranges in batched calls. | Reads request rows and writes batched status updates to a practice tab. |
| Custom functions | Formula-driven calculations returned directly to spreadsheet cells. | Returns computed values to calling cells without side effects. |
| Sheets validation and formatting | Adding data validation rules, conditional formats, and edit timestamps. | Modifies validation rules, formatting, and edit timestamps on a practice tab. |
| HTTP request preview | Inspecting a request before sending it. | Logs a request description; does not contact the sample host. |
| Public forecast | Validating external JSON before one bounded Sheets write. | Makes one public GET and replaces the reserved Forecast!A1:C12, including attribution. |
| Public repository sample | Paginated reads with separate record, page, and retry bounds. | Reads bounded public GitHub metadata and logs a possibly partial sample. |
| Persisted request policy | Historical local decisions, per-user preferences, and disposable cache. | Writes named Properties and cache entries; does not book a room or send a message. |
| Safe time-driven triggers | Installing and removing repeat-safe clock triggers under lock. | Creates an hourly trigger and updates blank statuses without duplicate triggers. |
| Request tracker | The continuing Sheets automation combining batching, state, and triggers. | Updates request rows and can install a time-driven trigger. |
| Drive file copy | Copying a known Drive file by ID into a destination folder and recording the created file ID. | Copies one configured template file into a selected Drive folder and stores the copy ID in Script Properties. |
| Docs report generation | Copying a Docs template, replacing text placeholders, and styling tables. | Creates a copied document and writes formatted briefing tables. |
| Gmail draft preparation | Searching test threads, creating drafts, and reconciling draft state with the Gmail advanced service. | Searches matching threads, creates Gmail drafts, and records draft IDs in Script Properties without sending mail by default. |
| Known Calendar events | Dates, instants, stored identities, and uncertain-create reconciliation. | Creates or updates bounded practice events in a selected secondary calendar. |
| Private workshop form | Branching, quiz feedback, native submission events, and known response IDs. | Creates a practice form and an owner-installed trigger; the optional exercise stores fictional submissions. |
| Slides briefing deck | Creating presentations, positioning shapes, and inserting metric cards. | Creates a two-slide briefing deck in Google Drive. |
| Advanced Drive service | Direct Google API calls with the Drive v3 advanced service. | Queries Drive metadata with field masks without modifying files. |
| Bound Sheets menu | Reading a selected request through a menu or sidebar. | Reads the selected row; does not write data. |
| Request-status web app | Deploying doGet endpoints, HTML service templates, and user authorization. | Serves a private HTML lookup page from a standalone project connected to a practice spreadsheet. |
| Custom event receipts | An authenticated sender and receiver contract and retained duplicate identity. | Sends bounded HTTP events and writes the receiver's receipt ledger; does not send email or create files. |
| Workspace add-on | Drive homepage trigger, CardService cards, validated card actions, and user-scoped state. | Renders a personal checklist card in the Drive side panel and stores user-scoped state without reading Drive files. |
| myFunction extension | In-editor type checking, error diagnostics, and safe refactors. | Analyzes code inside the browser editor without changing execution behavior. |
| Request tracker diagnostics | Execution timing, debugger breakpoints, structured logs, and resuming batches. | Inspects spreadsheet rows and manages batch checkpoints in Script Properties. |
| Local request summary | A small local clasp workflow for a bound script. | Reads a sheet and writes one execution-log line. |
| Test Apps Script code | Pure helper unit tests with Node.js and editor smoke tests on Sheets. | Runs local assertions; smoke test creates and removes a disposable test tab. |
| TypeScript builds | Compiling TypeScript with tsc into upload-ready .gs files for clasp. | Compiles local .ts files into verified .gs output without changing runtime behavior. |
| Versioned request planner | A producer's public calculation and a consumer's pinned version selection. | Calculates fictional input and logs results; setup creates private projects and numbered library releases. |
| Separate OAuth grant | Consent, callback, per-user token storage, refresh, and revocation. | Configures and changes a provider grant, reads a fixed practice range, and maintains local credential state. |
| Use AI models from Apps Script | Structured JSON outputs, schema validation, and checkpointed batches. | Calls Gemini, OpenAI, or Anthropic APIs and writes validated suggestions to Sheets. |
| Google Chat app | Direct-message events, interactive Chat cards, card updates, and removal lifecycle. | Responds to direct-message request lookups with interactive cards and updates card state in Google Chat. |
| GitHub issues and Actions events | Scoped GitHub REST reads from Apps Script and signed event receipts from GitHub Actions. | Reads one configured private issue via the GitHub REST API and records a signed Actions receipt in the custom endpoint. |
| Known embedded chart | Data versus presentation, builders, and stable output identity. | Creates and updates one chart in a selected practice spreadsheet; uncertain creation requires inspection, not another insert. |
| File format bundles | Validating tabular input and packaging CSV, JSON, and a Doc-exported PDF into a ZIP archive. | Reads a practice sheet, exports a Google Doc to PDF, and creates one private ZIP bundle in Google Drive. |
Reference map
Choose the narrowest maintained reference for the question:
Need a method signature or service behavior? Use the official Apps Script reference, then the site's Google Sheets service guide when it has a curated page.
Need a self-contained recipe? Start with the task guides, such as importing a web API or adding a custom Sheets menu.
Need a platform concept? Use the official guides, then return to the relevant book chapter for its place in the sequence.
Need current quotas, authorization scopes, or deployment guidance? Check the official documentation before relying on behavior that can change more often than a chapter's narrative.
For databases, domain-wide delegation, and BigQuery, start with the owning product's official documentation. Google Chat apps, AI integrations, and add-on publication have their own chapters, Post notifications to Google Chat, Use AI models from Apps Script, and Install and release a Workspace add-on, but their product documentation remains the authority for current policy. Each integration has its own authorization, billing, operational, and policy requirements.
When you need to maintain a project rather than learn a new feature, return to debugging and quotas and local development.