Previewing and Troubleshooting

Preview lets you test a Page or Form and its Page Flow behavior before publishing the Project.

Use Preview to verify startup logic, user interactions, modal Forms, Widgets, Project data operations, and calls to Cloud Flow. Testing the complete user experience helps you find problems that are not apparent from the Page Flow canvas alone.

This page explains how to prepare for testing, identify where a problem occurs, and troubleshoot common Page Flow issues. For general Page and Form preview behavior, see Previewing.

Understanding Save, Preview, and Publish

Saving, previewing, and publishing are separate steps.

Action	Purpose
Save in the Page Editor	Retains changes to the Page or Form's visual content and element configuration.
Save in Page Flow	Retains the Page Flow and generates the JavaScript used by the browser-side runtime.
Preview	Tests the saved development version of the Page or Form and its configured behavior.
Publish Project	Releases the Project's current development state to the published application.
Launch Project	Opens the published application so you can verify its released behavior.

Changes in the Page Editor and Page Flow should be saved before testing their combined behavior. Preview does not publish your changes, and a successful Page Flow save does not guarantee that every runtime operation will succeed.

For example, a flow may save successfully but still reference a renamed Page Element, receive an unexpected query result, or encounter a permission error when it runs.

Preparing to Preview

Before testing Page Flow:

1. Save Page Elements, Element Settings, and other visual changes in the Page Editor.
2. Open Flow and confirm that the intended blocks are present, enabled, connected, and configured.
3. Save Page Flow, correcting any reported JavaScript validation errors.
4. Confirm that referenced Forms, Widgets, Data Designs, tables, queries, and Cloud Flow web hooks are configured.
5. Open Preview and begin testing from the user action or Page state that starts the workflow.
6. Repeat the test after each meaningful correction.

Opening Preview automatically starts the Cloud Flow development test runtime when it is not already running. Manual Start Test is only needed when testing backend logic independently of a Page or Form. The runtime automatically stops two hours after it starts; opening Preview again starts it when needed. For details, see Testing and Logs.

If you have added or renamed an element in the Page Editor, save the visual changes before selecting or referencing that element in Page Flow. Some editor selectors use the saved Page structure rather than unsaved visual edits.

Use Representative Test Data

A Page that works with one ideal record may behave differently with real data.

Include cases such as:

• No matching records.
• One record and many records.
• Missing or empty optional values.
• Long text and unexpected input formats.
• Records belonging to different Project Users or User Groups.
• Existing records that may have changed since the Page first loaded.
• Operations that succeed and operations that fail.

When Preview calls a Database operation, Cloud Flow, or external service, consider the selected environment and the data involved. Preview is a development test, not a guarantee that connected operations have no side effects. Use appropriate test records and provider test modes when available.

What to Test

Test both the initial Page experience and the interactions that follow.

Area	What to Verify
Startup	Initial values, visibility, event setup, and data loading happen as intended when the Page opens.
Buttons and menus	Actions trigger the correct Page Flow behavior and open the intended destination or interaction.
Page Elements	Content, styling, enabled states, and element references are updated correctly.
Inputs and validation	Valid input continues; invalid input produces useful feedback and prevents inappropriate submission.
Modal Forms	The correct Form opens, receives the expected edit data or shared context, and handles submit, success, error, and close.
Data Table Widgets	Loading, refresh, paging, selected-row actions, and attached Forms behave correctly.
Data Design	Placeholders receive the expected values and rendered items appear in the intended target area.
Database operations	Reads and permitted writes return the expected records or results under the current user's access rules.
Cloud Flow	Requests contain the intended input and the Page handles successful and failed results.
Custom Code	JavaScript executes as intended with the available values and browser-side capabilities.
Responsive behavior	Layout, dialogs, and interactive controls remain usable on desktop, tablet, and mobile widths.
Access	Users with different permissions see and can perform only the actions they are authorized to use.

Do not test only whether a Button can be clicked or a Form can open. Verify the result of the operation and the state of the surrounding Page afterward.

A Practical Troubleshooting Process

When behavior does not match your expectations, narrow down the problem before changing several blocks at once.

1. Reproduce the problem. Identify the Page, action, input values, and point where the expected behavior stops.
2. Check the saved state. Confirm that both visual Page changes and Page Flow changes have been saved.
3. Check the entry point. Determine whether the workflow should run during startup, on an event, during a Form lifecycle stage, or after an asynchronous operation.
4. Inspect the canvas. Confirm that relevant blocks are enabled, connected, and configured for the intended elements and resources.
5. Check inputs and context. Verify record IDs, field values, dataset names, shared Form context, and other values the workflow depends on.
6. Follow the result path. For operations that complete later, inspect the supported success, error, or completion path rather than assuming the next statement has the result.
7. Check permissions and backend dependencies. Verify Database access rules, web hook configuration, and any required Integration or Cloud Flow setup.
8. Isolate the failing section. Temporarily disable or simplify a small part of the flow if needed, then test again.
9. Correct, save, and Preview again. Re-run both the failing case and a related case that previously worked.

For complex flows, test one entry point or procedure at a time. This helps distinguish a problem in the Page Flow structure from a problem in the data or service it calls.

Identify Which Stage Failed

Stage	Typical Symptom	Start By Checking
Editor configuration	A reference is unavailable or the wrong element is selected.	Saved Page content, element name, and block configuration.
Saving	Page Flow cannot be saved because of invalid JavaScript.	The reported Custom Code or Code Expression block.
Startup or event registration	An action does not run at all.	Entry point, event configuration, disabled blocks, and connections.
Runtime execution	The action begins but stops or shows the wrong result.	Field values, conditions, custom JavaScript, and asynchronous paths.
Data or service call	A request fails or returns unexpected data.	Query or web hook inputs, result handling, and access rules.
Page update	Data changes but the visible content stays stale.	Data Table refresh, Data Design rendering target, and follow-up logic.

Common Issues and How to Resolve Them

A Block Has No Effect

Check whether the block is disabled. Disabled blocks remain on the canvas but do not contribute the intended behavior.

Next, check whether the block belongs to the correct execution path:

• Is it connected to the expected startup or event-driven logic?
• Is it inside a procedure that is actually called?
• Does an earlier condition prevent that path from running?
• Does execution depend on an asynchronous result that has not arrived?

The Flow Start block is an organizational marker, not a mandatory execution root. A block's behavior depends on its actual execution context, not merely on whether it appears beneath Flow Start.

For details about startup and events, see Events and Startup.

A Button or Menu Action Does Not Run

Confirm that:

1. The correct Button, Link, or menu control is selected and referenced.
2. Its supported action or event has been configured.
3. The event-driven logic is enabled.
4. The event is the one the user actually triggers.
5. No earlier condition or runtime failure prevents the expected action.

If an element was replaced in the Page Editor, the new element may require updating references in Page Flow, even when its visible label looks identical.

A Page Element Is Not Found

Verify that the element exists in the saved Page or Form, and that the Page Flow block references the intended element.

Common causes include:

• Adding or renaming an element without saving the Page Editor changes.
• Selecting a parent Container instead of the child element you intended to change.
• Deleting or replacing an element that Page Flow still references.
• Importing or duplicating blocks whose references belong to another Page or Form.
• Referring to content created dynamically as though it were an ordinary static Page Element.

When working with Data Design, check the rendered instance and its identifiers as appropriate rather than assuming that a design's source element is the same as a rendered element.

For details, see Selected Element Toolbar and Rendering Data Design.

Startup Logic Does Not Produce the Expected Page State

Check the order in which initial content, event handlers, and data requests are prepared.

For example, a Page may initially show a placeholder message while a Database request is pending. The final message should be updated only when the request completes and the result has been checked.

If multiple startup tasks change the same element, determine which task runs last. If they are asynchronous, completion order may not match the order in which requests started.

Avoid relying on one operation's result before that operation has completed.

A Form Does Not Open

Confirm that:

• The intended Form exists and is configured as a Form in Pages & Forms.
• The opening Button, Data Table action, or Page Flow sequence refers to the correct Form.
• The modal-opening operation is reached.
• Any required input or context for the opening operation is present.
• The Page has been saved and its flow has been saved.

For a Form opened from a Data Table, test the actual New or Edit action rather than trying to reproduce the problem by opening the Form alone.

A Form Opens with Missing or Incorrect Values

Distinguish the information supplied to the Form:

Information	Purpose
Edit data	Identifies and initializes the existing record being edited.
Shared context	Supplies additional information from the opening Page to New, Edit, or Custom Form workflows.
Current Form data	Represents the values presently entered into the Form fields.

A New Form may receive shared context without being in Edit mode. An Edit Form may receive both edit data and shared context.

If a Form opens with blank or wrong values, check the opening Page's supplied data, the Form's field bindings, and Form Page Flow initialization. Do not infer Edit mode from a heading or Button label alone.

For details, see Opening Forms as Modals and Form Page Flow.

A Form Submits but the Page Does Not Update

First confirm whether submission actually succeeded. Opening a modal, clicking Submit, and closing the modal are different events from a successful operation.

If the operation succeeded, check whether the opening Page's success path refreshes the relevant Data Table or updates the displayed summary.

For a Custom Form, confirm that its configured submission workflow reports completion and does not show success merely because processing started.

If the submission failed or was cancelled, the opening Page should not display a successful result or refresh as though the operation completed.

Data Does Not Load or Shows Unexpected Records

Review the Database operation and the context it uses.

Check:

• The selected Project table or named query.
• Query input, criteria, and any expected filters.
• The dataset name or destination used by the operation.
• Whether the data request completed successfully.
• Whether the current Project User has access to the requested records.
• Whether the interface is showing an older dataset or requires a refresh.

An empty result is not necessarily an error. Distinguish no matching records from request failed, and give users appropriate feedback for each state.

Do not treat client-side filtering, hiding columns, or hiding controls as protection for restricted data. Database permissions and trusted Backend checks govern authorization.

A Data Table Does Not Refresh

A successful create or update does not always mean the already displayed rows refresh without additional configuration.

Confirm that the Page Flow success path refreshes the appropriate Data Table. If the Data Table uses Custom Query, verify that its current query inputs and result source still describe the records you intend to display.

Also check pagination and filtering: the new or edited record may not appear in the current visible page even when the refresh works correctly.

For more information, see Data Table Widget.

Data Design Output Is Missing or Repeated Incorrectly

Check the entire rendering sequence:

1. The Data Design contains the intended Page Elements and placeholders.
2. The data supplied for each item matches its placeholder Field Names.
3. The intended rendering target exists and is selected.
4. Any IDs or ID2 values needed for item-specific behavior are supplied appropriately.
5. The workflow chooses the correct treatment of prior output before rendering again.

For example, search results may need to replace earlier results rather than append duplicates. Conversely, a Load More interaction may intentionally append new items.

Test zero, one, and multiple items, including records with missing or long values. For rendering concepts and techniques, see Rendering Data Design.

A Cloud Flow Call Fails

When Page Flow invokes Cloud Flow, inspect both sides of the operation.

On the Page Flow side, check:

• The intended Cloud Flow web hook or configured target.
• The data supplied to the call.
• The success, failure, or completion path used by the calling block.
• Whether the returned values are interpreted correctly.

On the Backend side, check that the Cloud Flow exists, accepts the expected input, has the necessary access and Integration configuration, and returns the expected result for the request.

Preview starts the Cloud Flow development test runtime when needed, but the runtime automatically stops two hours after it starts. If a Cloud Flow call fails during a long-running Preview session, close and open Preview again before repeating the test. For backend activity and test logs, see Testing and Logs.

Page Flow should show an appropriate error or recovery message when the trusted operation fails. Avoid showing success before the server-side work reports success.

For implementation guidance, see Data and Cloud Flow.

A Result Object Is Misinterpreted

Some ioLoop operations expose Result Objects with values such as status, data, and err. Other operations, including HTTP-oriented blocks, can expose different values or separate data and error paths.

Use the result-handling behavior documented for the particular block. Do not assume every operation returns the same object shape.

In general:

1. Check the operation's success or failure status using its supported mechanism.
2. Read data only when a usable result is available.
3. Read or handle error information when the operation fails.
4. Update the Page based on the actual outcome.

For exact output and status conventions, see Result Objects and HTTP and Web Hooks.

Custom Code Prevents Saving

When saving Page Flow, ioLoop validates enabled Custom Code and Code Expression blocks. Invalid JavaScript in one of these blocks stops the save and causes the editor to report an error.

Check the reported block and correct its syntax.

A Code Expression must contain one JavaScript expression, not multiple statements. Avoid top-level await, trailing semicolons, and other syntax that is invalid in the expression's supported position.

Use Custom Code for JavaScript statements or multi-step logic. Disabled custom code blocks are excluded from the save-time validation path while disabled.

Passing this syntax validation only means the editor accepted the code at save time. The code must still be tested with actual data and browser-side conditions.

For details, see Custom Code.

Custom Code Saves but Fails at Runtime

A runtime issue may be caused by a missing value, unavailable function, unexpected result, or an assumption about where variables are defined.

Check that:

• Values used by the code are initialized before they are read.
• The code uses supported browser-side APIs.
• A function provided by a frontend Code asset is actually included on the Page.
• Values needed by other blocks are shared using the documented mechanism rather than assumed to be in scope.
• A failed asynchronous operation is handled rather than treated as a valid result.

For example, local let or const variables declared inside a Custom Code block should not be assumed to be available in unrelated blocks. Use documented flow-sharing facilities when data must be shared.

Browser developer tools, such as the JavaScript console or Network panel, can help investigate runtime errors and requests where available. These are browser debugging tools, not special Page Flow editor features. Avoid exposing credentials, tokens, or sensitive record data in diagnostic output.

Preview Works but the Published Page Behaves Differently

Confirm that the relevant changes have been published. Saving and previewing development changes does not update the published application.

Also compare the environment and configuration involved:

• Are the same Page settings and access rules in effect?
• Are integrations using the intended test or live configuration?
• Is the published Page using the expected URLs and assets?
• Are the test and published users permitted to perform the same operations?

After publishing, use Launch Project to verify the released Page. See Publish Project and Launch Project.

Troubleshooting Asynchronous Workflows

Database requests, HTTP operations, Cloud Flow calls, and other deferred work may complete after the statements that initiated them.

A common problem is trying to use a result before it exists.

Consider this conceptual sequence:

User selects Search
  Begin data request
  Wait for supported result/completion path
    Success
      Check returned data
      Render results
    Failure
      Show error message

This illustrates execution responsibilities, not exact Page Flow block names.

For asynchronous workflows:

• Use the block's documented result, callback, or completion mechanism.
• Keep loading or pending states understandable to users.
• Avoid allowing conflicting operations when they would create incorrect results.
• Consider what should happen if the user changes a filter or navigates away before a request completes.
• Do not assume that two independent requests finish in the order they started.
• Ensure error paths give the user a useful next step.

If a Page makes several requests, isolate and test each result path before combining them into a larger workflow.

Example: Troubleshooting a Customer Edit Workflow

Consider a Customers Page containing a Data Table Widget and a table-backed Customer Form.

The intended sequence is:

Customers Page
  Data Table Edit action
    Open Customer Form with selected record edit data
      Load existing values
      Submit update
        Success -> Refresh Customers Data Table
        Failure -> Show Form error

If the wrong customer appears, start with the selected record context passed to the Form. Verify the record identity and the Form's field bindings.

If the correct customer appears but the update fails, inspect validation, Database permissions, and any trusted Backend processing.

If the update succeeds but the old value remains visible, check the opening Page's success path and Data Table refresh behavior, including active filters or paging.

If the user cancels the Form, confirm that the opening Page does not treat cancellation as a successful update.

Breaking the workflow into these stages is usually more effective than changing the entire Page Flow at once.

Testing Access and Security

Page Flow executes in the browser. It can use permitted Project data operations and coordinate trusted Cloud Flow processing, but it is not itself a secure authorization boundary.

Test workflows with the users and permissions the application expects. In particular:

• Verify access for public and authenticated Pages as applicable.
• Confirm that Project Users and User Groups can access only their permitted records and operations.
• Check that Backend authorization still applies when a browser-side value is changed or a hidden control is bypassed.
• Keep secrets and private provider credentials in trusted Project capabilities.
• Confirm that failed authorization produces appropriate feedback without disclosing protected information.

A hidden Button, disabled Form field, or invisible menu item is not a substitute for Database access rules or Backend authorization.

Good Practices

• Save before testing. Save both Page content and Page Flow changes so Preview uses the intended configuration.
• Test complete workflows. Begin with the real Button, Form, Widget, or event that starts the user experience.
• Use representative data. Include empty results, long values, invalid inputs, and realistic record counts.
• Keep flows understandable. Use named procedures, comments, and focused block groups on the canvas.
• Check asynchronous results. Update the Page after the operation completes through its supported result path.
• Distinguish errors from empty results. Tell users whether no records matched or an operation failed.
• Preserve user input when appropriate. After failed Form submissions, allow users to correct values instead of needlessly starting over.
• Test access boundaries. Verify permissions and trusted processing independently of visual controls.
• Retest after fixing a problem. Confirm that the correction works and has not broken another workflow.
• Verify after publishing. Test the released application using Launch Project.

Common Mistakes

Avoid these patterns:

• Previewing before saving the latest Page Elements or Page Flow.
• Assuming a block executes just because it is visible on the canvas.
• Forgetting that a block or surrounding logic has been disabled.
• Continuing before an asynchronous operation returns a result.
• Referencing an element that was deleted, replaced, or not yet saved.
• Confusing a Form's edit data with shared context or current field values.
• Treating Form closure or submission initiation as confirmed success.
• Refreshing a table after an unsuccessful or cancelled operation.
• Appending new Data Design output without addressing earlier results.
• Assuming an empty dataset always means an error.
• Assuming save-time JavaScript validation guarantees runtime correctness.
• Treating browser-side visibility or validation as security enforcement.
• Testing only with an administrator account or only with successful input.
• Assuming Preview and the published application are the same state.

Page Flow troubleshooting is most effective when you identify the precise stage that failed: the saved Page configuration, the event or startup path, the operation's inputs, the result returned, or the final Page update. Test each stage in order and verify the complete workflow before publishing.

Related Topics

• Page Flow
• Editor Basics
• Choosing Blocks
• Events and Startup
• Data and Cloud Flow
• Cloud Flow Testing and Logs
• Forms and Widgets
• Custom Code
• Previewing
• Page Flow Blocks
• Client API