Frequently Asked Questions

This section collects common issues and solutions you may encounter when deploying and using SmartTable. If your issue is not covered here, please contact us via the "Issue Feedback" button in the top-right corner or through GitHub Issues.

Deployment & Installation

Docker deployment is inaccessible after startup

Symptom: After running docker run, the browser shows connection refused or 502 when accessing http://localhost.

Solution:

1. Confirm the container is running: docker ps and check that the status is Up.
2. View container logs: docker logs <container_id> to check for port conflicts or startup errors.
3. Confirm the port mapping is correct, e.g., -p 80:80 maps container port 80 to host port 80.
4. If port 80 is occupied, use a different port such as -p 8080:80 and access http://localhost:8080.
5. Check whether the firewall or security group allows the corresponding port.

Windows startup package flashes and exits when running start.bat

Symptom: Double-clicking start.bat causes a black window to flash and the service does not start.

Solution:

1. Do not double-click directly. Instead, run start.bat in PowerShell or CMD to see the full error output.
2. Check whether antivirus software has blocked the program; add the package directory to the whitelist if necessary.
3. Make sure the path does not contain Chinese or special characters; it is recommended to place it in a pure English path.
4. Check the log files in the logs/ directory for specific errors.

Backend logs show Redis connection failure

Symptom: Startup reports ConnectionError or Redis is not running.

Solution:

1. Docker deployment includes Redis by default. For manual deployment, Redis must be installed and started separately.
2. Check whether REDIS_URL in .env or environment variables is configured correctly.
3. If real-time collaboration is not needed, disable it in system settings or set ENABLE_REALTIME=false.
4. Use redis-cli ping to test whether Redis is reachable.

Will data be lost after upgrading from an older version?

Solution:

1. On first startup after an upgrade, the database migration (Alembic) runs automatically; existing data will not be lost.
2. Still, it is recommended to back up data/ (database), uploads/ (attachments) and config/.env (configuration) before upgrading.
3. When upgrading the Docker image, keep the smarttable_data, smarttable_uploads and smarttable_redis volumes to preserve your data.
4. Since v1.6.6 the PostgreSQL driver is psycopg, so DATABASE_URL must use the postgresql+psycopg:// prefix.

PostgreSQL mode fails to create tables or migrate

Symptom: After switching to PostgreSQL, errors such as relation does not exist or migration failures appear.

Solution:

1. Confirm the database has been created in advance and the user has permissions to create tables and extensions.
2. Alembic will automatically run migrations on first startup; make sure the working directory is correct (run from smarttable-backend).
3. If migration versions are inconsistent, manually run python run.py migrate.
4. Check that the DATABASE_URL format is correct, e.g., postgresql+psycopg://user:pass@host:5432/dbname.

Login & Permissions

"Login expired" appears shortly after logging in

Symptom: After using for a while, refreshing the page redirects to the login page.

Solution:

1. v1.6.3 supports Token auto-refresh. Make sure both frontend and backend are upgraded to v1.6.3.
2. Check the "Session timeout" in system settings. The default is short; adjust it as needed (not recommended to exceed 7 days).
3. If using a reverse proxy, confirm it does not filter or cache JWT-related headers.
4. Clear browser cache and log in again.

Registration entry is missing or registration is disabled

Symptom: The login page has no "Register" button, or clicking register prompts "Registration is closed".

Solution:

1. Administrators can enable or disable registration in "System Management → System Settings".
2. If registration is disabled, users can only be created manually by an administrator.
3. Check whether the current user has the administrator role.

Editors (EDITOR) cannot create fields, workflows or dashboards

Symptom: Editor-role users cannot find field management or workflow entries, or receive permission errors.

Solution:

1. Since v1.6.4, field-related and management operations (field management, workflows, tables, documents, dashboards, etc.) require the ADMIN role or above.
2. Ask the Base owner to promote the user to admin in member management, or let an admin perform the operation.

Tables & Fields

Formula field shows "#ERROR" or incorrect result

Symptom: After configuring a formula field, the cell shows an error or does not calculate.

Solution:

1. Check whether the formula syntax is correct. It is recommended to use the "Formula Helper" in the field configuration panel.
2. Confirm the referenced field names or IDs have not changed; if changed, re-edit the formula.
3. v1.6.3 unified frontend and backend formula function registration. If errors persist after upgrading, check whether an unsupported function is used.
4. Numeric, date, and other field types are automatically converted in formulas; pay attention to type matching.

Link/Lookup field data does not refresh or displays incorrectly

Symptom: After selecting a link field, the lookup field does not update synchronously or shows stale data.

Solution:

1. v1.6.3 fixed the issue of link field cache not refreshing; please upgrade to the latest version first.
2. Refresh the page or reopen the record drawer.
3. Check whether the link field relationship type is configured correctly; if changed, save the field again.
4. Confirm the target field referenced by the lookup field has a valid value in the linked record.

Adding a record creates two rows at once

Symptom: Clicking "Add record" produces two blank rows in the table.

Solution:

1. This is an editor callback anomaly fixed in v1.6.3; upgrading will resolve it.
2. If it still occurs after upgrading, check the browser console for errors and submit via "Issue Feedback".

Number field always defaults to 0

Symptom: Number field automatically shows 0 when not filled in.

Solution:

1. v1.6.3 optimized number field default rules to automatically decide whether to write 0 or empty based on the default value setting.
2. If customization is needed, set the "Default value" to empty or a specific value in the field configuration.
3. Also check whether the "Decimal places" setting for the number field takes effect.

Views & Interaction

Kanban card drag does not change the group

Symptom: Dragging a card to another column in Kanban view returns to the original column after refresh.

Solution:

1. v1.6.3 fixed the issue where Kanban drag did not use the target group ID; upgrading will resolve it.
2. Confirm the group field value corresponding to the target column matches the card's intended value.
3. Check whether the current user has edit permission for the table.

Multiple users on the same LAN are rate-limited when submitting a shared form

Symptom: When several users submit the same shared form at the same time, some receive a "too many requests" prompt.

Solution:

1. Since v1.6.4, the share form rate limit is counted per share token (100 requests / 15 minutes per form) instead of per client IP, so multiple users behind the same LAN no longer interfere with each other.
2. If the limit is still triggered (e.g. high-frequency automated submission), retry later or integrate via the Open API instead.

Large tables load slowly

Symptom: When there are tens of thousands of records, the table first screen takes several seconds or longer to load.

Solution:

1. SmartTable supports streaming load: first screen loads part of the data, remaining pages load asynchronously in the background.
2. Reduce the number of records per page, or configure appropriate filter conditions in the view.
3. Create indexes for frequently queried fields (more effective in PostgreSQL mode).
4. Disable unnecessary real-time collaboration to reduce WebSocket data transfer.

Attachment upload fails or cannot be previewed

Symptom: Clicking upload does nothing, or thumbnails do not display after upload.

Solution:

1. Check the "File count limit" and "File size limit" of the attachment field; the server-side single file limit is 50MB.
2. Confirm the upload directory has write permissions; Docker deployment requires persistent storage volume.
3. v1.6.3 supports single-click thumbnail preview of full image; if preview fails, check whether the browser blocked the popup.
4. Check backend logs for MIME type or file content security validation failures.

Geo location field is missing or the map picker is empty

Symptom: The geo location field type cannot be found, or the map picker component appears blank.

Solution:

1. The geo location field (added in v1.6.6) is based on the Tianditu map service. Configure TIANDITU_KEY in the server environment variables (apply at https://console.tianditu.gov.cn).
2. Without TIANDITU_KEY, the frontend automatically hides map-related entries; refresh the page after configuring.
3. For private deployments, replace the Tianditu service address via TIANDITU_API_BASE.

Workflow

Workflow does not trigger after saving

Symptom: After configuring triggers and nodes, the workflow does not execute when records are created/updated.

Solution:

1. Confirm the workflow status is "Running"; paused or draft workflows will not trigger.
2. Check whether trigger filter conditions are configured correctly, paying attention to AND/OR logic.
3. Confirm the fields monitored by the trigger actually changed during the update.
4. View "Execution Logs" to check for errors or node execution failures.

Loop node does not execute or data is empty

Symptom: Loop node status shows skipped, or the loop body does not execute.

Solution:

1. Confirm the loop data source type is configured correctly:
   • When iterating over all results from a find records node, use find_records_all.
   • When extracting values of a specific field, use find_records_column.
2. Check whether the find records node returned valid data.
3. Node IDs inside the loop body must be correctly mapped to backend UUIDs when saving.
4. View diagnostic information such as skipped_reason and data_array in the execution logs.

Webhook node recipient does not receive the request

Symptom: Workflow execution shows success, but the recipient system does not receive the Webhook.

Solution:

1. Check whether the Webhook URL is correct and has no extra spaces.
2. View "Webhook Delivery Logs" to confirm whether the request was sent and what the response status code was.
3. Confirm the recipient server can access the network where SmartTable is deployed (especially important for intranet deployments).
4. Check whether Webhook headers and body templates are rendered correctly to avoid request dropping due to variable resolution failure.

Custom script node fails or produces no output

Symptom: A workflow Python script node (added in v1.6.4) errors out or returns an empty result.

Solution:

1. Scripts run in a server-side sandbox as an isolated subprocess with a restricted environment. Use the "Test Run" button in the node configuration panel to verify script logic first.
2. Script results have a size limit (about 1MB); avoid constructing or returning oversized objects in scripts.
3. Check Python syntax and variable references, and inspect the "Execution Logs" for error details.

Real-time Collaboration

Online users not shown or collaboration status abnormal

Symptom: When multiple users edit simultaneously, other users are not visible or lock status is out of sync.

Solution:

1. Confirm real-time collaboration is enabled and Redis is running normally.
2. Check the browser console for WebSocket connection failure errors.
3. If using a reverse proxy or Nginx, confirm WebSocket forwarding is correctly configured (for /socket.io/ path).
4. v1.6.3 fixed timezone acquisition logic to support reading the browser's local timezone, avoiding collaboration anomalies caused by timezone inconsistency.

Email & Notifications

Email sending fails

Symptom: After configuring SMTP, test sending or workflow email node sending fails.

Solution:

1. Check SMTP server address, port, encryption method (TLS/SSL), and authentication information.
2. Confirm SMTP service is enabled for the mailbox; some providers require a separate authorization code.
3. Check email sending logs to see if messages were blocked by the provider or sent to spam.
4. For enterprise email, confirm there are no sending rate limits or IP whitelist restrictions.

No notifications received

Symptom: No notification is received for collaboration invitations, approvals, etc.

Solution:

1. Since v1.6.4, notifications are delivered primarily via in-app messages (the bell icon in the top-right corner). Check there first.
2. If in-app messages arrive but emails do not, check the SMTP configuration in the admin console under System Settings and use the test send feature.
3. Since v1.6.6, links in email notifications are generated from the "Platform entry domain" setting; if links point to the wrong address, configure it in System Settings.

Performance & Browser

Page lags or browser crashes

Symptom: Browser becomes laggy or even crashes when opening large tables or complex dashboards.

Solution:

1. Reduce the number of simultaneously expanded views and dashboard components.
2. Configure appropriate filter conditions for large tables to avoid loading full data at once.
3. Use modern browsers such as Chrome or Edge, and keep them updated.
4. Close unused browser extensions to avoid excessive memory usage.

Others

Timezone display is incorrect

Symptom: Date Time fields show times inconsistent with expectations.

Solution:

1. Configure the correct system timezone in "System Management → System Settings".
2. If timezone mode is "Local timezone", it will prefer the configured timezone_name; if not configured, it will use the browser's local timezone.
3. If timezone mode is "UTC", all times will be displayed in UTC.
4. Refresh the page after switching timezone for the configuration to take effect.

How to submit bugs or feature suggestions

Solution:

1. Click the "Issue Feedback" button in the top-right corner, fill in the description, and attach screenshots and logs.
2. Submit via GitHub Issues: https://github.com/ldbinac/smart_table/issues
3. Follow the WeChat official account "程序员吕洞宾" for the latest updates.

How to switch the interface language

Solution:

1. Since v1.6.5, both Chinese and English interfaces are supported. Switch manually via the language selector in the top-right corner.
2. If not selected manually, the system automatically detects the browser language.

How to develop or install plugins

Solution:

1. v1.6.6 introduced the plugin extension system, allowing table capabilities to be extended via plugins. The project ships with frontend and backend sample plugins (hello-panel).
2. See the developer documentation: Plugin Architecture and Plugin Developer Guide.