ZenotiHelp

Troubleshoot analytics data issues

ZTZenoti Docs Team Updated November 9, 2026 5 min readGuide

Use this article to diagnose and resolve common issues when working with Analytics β€” Amazon S3 data.

Before you begin

  • Your organization must have an active Analytics β€” Amazon S3 subscription.
  • You need read access to your S3 bucket to check GroupID folders and processing status.

Data appears stale or has not updated

Symptom: Your reports show outdated information, or the most recent transactions from Zenoti are not visible in your warehouse.

What to check:

  1. Look for recent GroupID folders in your S3 bucket. If the newest GroupID folder was written several hours ago and no new folder has appeared, a data refresh may be delayed or stalled.

  2. Check for _processing folders. A GroupID folder with a _processing suffix (e.g., 4_processing/) means a data load is currently in progress. Wait for the suffix to be removed before loading that data. This is expected during an active refresh cycle.

  3. Check the load timestamps in your warehouse. Query the etlcreateddate or EtlLastUpdatedOn columns on any recently loaded table. The maximum value tells you when data was last written.

`sql SELECT MAX(etlcreateddate) AS last_loaded FROM Bi_FactInvoiceItem WHERE void = 0;

Action: If no new GroupID folder has appeared in your S3 bucket beyond the typical 1–2 hour cadence and no _processing folder is present, contact Zenoti Support with the name of your S3 bucket and the last GroupID you received.

Empty table folders in a GroupID

Symptom: A GroupID folder exists in your S3 bucket but one or more table subfolders are empty or missing.

Explanation: This is expected behavior. Incremental GroupID loads contain only tables that had changed data since the previous load. If a table had no changes in a given cycle, it will not appear in that GroupID folder.

What to check:

  • If a table is missing from every incremental GroupID, verify that the table exists in GroupID 1 (the initial full load). GroupID 1 always contains all tables.
  • If the table is absent from GroupID 1 as well, it may not be included in your subscription scope. Contact Zenoti Support to confirm.

Missing data for a specific center

Symptom: Transactions, appointments, or records for a particular center are absent from your data.

What to check:

  1. Verify your subscription scope. A center-level subscription includes only that center's data. A zone or org-level subscription includes data across all centers in your scope. Filter by centerid or join to Bi_DimCenter to isolate center-specific data.

  2. Check whether the center is newly onboarded. Centers added to Zenoti after your initial data load may not be included in historical data. They appear in data refreshes going forward from their onboarding date.

  3. Confirm the center's status. Inactive or closed centers may have their data suppressed in certain table views.

Action: If you believe a center should be in your data but is absent, contact the Zenoti Implementation team to verify that the center is included in your subscription scope.

Duplicate records in queries

Symptom: Aggregations return inflated numbers, or row counts are higher than expected.

What to check:

  1. Filter void = 0 on all fact tables. Fact tables contain both current records (void = 0) and soft-deleted records (void = 1). If you do not filter on void, you will count the same logical record multiple times.

`sql -- Incorrect β€” counts void=1 records SELECT COUNT(*) FROM Bi_FactInvoiceItem;

-- Correct β€” counts only current records SELECT COUNT(*) FROM Bi_FactInvoiceItem WHERE void = 0;

  1. Check your incremental load logic. If you are applying incremental GroupID data without removing void = 1 records, you will accumulate both the original and updated version of each record. The correct pattern is:
  • Delete rows from your warehouse where the key matches a void = 1 row in the new GroupID.
  • Insert all void = 0 rows from the new GroupID.
  1. Check for accidental multi-GroupID duplication. If your load process inserts all rows from multiple GroupIDs without deduplication, the same record key may exist multiple times. Always apply the delete-insert pattern for each incremental GroupID in sequence.

Column count mismatch when loading CSV

Symptom: Your CSV loader reports a column count error, or data appears in the wrong columns after loading.

What to check:

  1. CSV files have no column headers. The first row in every CSV file is data, not a header row. If your loader is configured to treat the first row as a header, it will consume the first data row as column names and shift all subsequent rows by one. Set SKIP_HEADER = 0 or header = False in your loader configuration.

  2. Verify you are using the correct schema version. If Zenoti has released a schema upgrade since you last reviewed SchemaFull, new columns may have been added. A schema definition with fewer columns than the data file causes a column count mismatch.

Action: Check the SchemaUpgrade folder for any new version subfolders you have not yet applied. See Handle schema changes and upgrades for guidance.

Cannot connect to the S3 bucket

Symptom: Your S3 client returns an Access Denied, NoCredentialProviders, or InvalidAccessKeyId error.

What to check:

  1. Verify your AWS credentials. Confirm the access key ID and secret access key configured in your client are correct and have not expired or been rotated.

  2. Check network access restrictions. If your organization or the S3 bucket policy restricts access by IP address or VPC, ensure you are connecting from an allowed network.

  3. Confirm the bucket name and region. An incorrect bucket name or AWS region in your client configuration results in a connection failure.

Action: If credentials have expired or you need new access credentials, contact the Zenoti Implementation team to request a credential refresh.

_processing folder persists for an unusually long time

Symptom: A GroupID folder with a _processing suffix has been present for several hours without being renamed.

Explanation: The _processing suffix is removed once a data load completes successfully. If it persists for an extended period, the data load may have encountered an error and did not complete. The folder is not renamed in this case.

What to do:

  1. Do not query or load data from a _processing folder. The data is incomplete and unreliable.

  2. Check subsequent GroupID folders. The next scheduled data refresh writes a new GroupID. If the subsequent GroupID completes successfully (no _processing suffix), you can resume loading from that folder.

  3. Contact Zenoti Support if multiple consecutive GroupID folders remain in _processing state, as this may indicate a broader issue with your data pipeline.

Schema mismatch after a Zenoti release

Symptom: After a Zenoti software release, CSV files fail to load because they contain more columns than your warehouse table definition.

Explanation: Zenoti periodically adds new columns to existing tables as part of product releases. New columns are appended to the end of each file, so existing columns remain in their original positions. However, your warehouse table must be updated to accommodate the new columns before loading the new data.

What to do:

  1. Check the SchemaUpgrade folder in your S3 bucket for new version subfolders.
  2. Review the upgrade files to identify which tables were changed and what columns were added.
  3. Apply ALTER TABLE... ADD COLUMN statements to your warehouse for each affected table.
  4. Resume loading data.

Tip: Check the SchemaUpgrade folder regularly β€” weekly or after any Zenoti release notification β€” to avoid schema mismatch errors. See Handle schema changes and upgrades for the full upgrade process.

Was this article helpful?
Your feedback helps us improve our documentation.