Skip to content
Markdownllms.txt

UAT release

This guide describes the upcoming portal update. Some screens or actions may differ in the current UAT portal.

Troubleshooting, FAQ & AI Assistant Integration ​

This guide covers common billing errors, role restrictions, sign-in and password recovery, meter connectivity diagnostics, and how to connect AI assistants and agents to the WattDee documentation.


1. Error 422: Missing Ft Rate When Generating an Invoice ​

Symptom ​

  • Calculation or invoice generation fails with HTTP 422: No Ft (Fuel Adjustment Tariff) rate is on record for YYYY-MM. Refusing to generate: billing would require inventing a rate.
  • A yellow banner at the top of /billing (or in the Dashboard Action Queue) prompts Ft verification required.

Cause ​

  1. Real invoices write financial amounts to the ledger, so the billing engine strictly refuses to invent an Energy Regulatory Commission (ERC) Ft rate when no verified record exists for YYYY-MM.
  2. Only a Platform Administrator (ftrate.write capability) can set or update Ft rates. Developer ADMIN and ACCOUNTING users cannot configure Ft rates themselves.

Step-by-Step Resolution ​

  1. Ask a Platform Administrator to sign in, open /billing, and click Verify Ft rate in the warning banner (or go to Settings → Billing & tariffs).
  2. Confirm the target YYYY-MM billing month and enter the official Ft rate (THB/kWh) (valid range: -2.0000 to 10.0000).
  3. Click Confirm, then retry invoice generation in /billing (see Billing & Approval Guide).

Why Does "Compare PPA rate with utility" Still Work Without an Ft Rate?

The Tariff Savings Comparison report (/api/billing/rate-comparison) is an exploratory comparison tool. When YYYY-MM has no configured Ft rate, it falls back to 0.3972 THB/kWh and displays a yellow warning banner so users know the savings preview is provisional.

Tariff savings comparison modal displaying the 0.3972 THB/kWh Ft fallback warning banner


2. Error 422: Billing Period Has Not Ended Yet (Open Period vs. invoice.issueEarly) ​

Symptom ​

  • Clicking Create bill before the billing cut-off date fails with HTTP 422: Billing period YYYY-MM has not ended (X/Y days elapsed)... or a message stating the period has not finished yet.

Cause ​

  • Under business rule BL-1, monthly invoices are generated after the billing cycle closes (endDate <= now, honoring billingCycleDay in Asia/Bangkok UTC+7).
  • Only users holding invoice.issueEarly (Developer ADMIN or Platform ADMIN) can confirm early issuance. Developer ACCOUNTING users cannot issue before cut-off, and future periods that have not started are blocked for everyone.

Step-by-Step Resolution ​

  1. Wait until after 00:00 Bangkok time on the site's cut-off date (cycleDay) to issue the full-month invoice.
  2. If an early mid-cycle bill is genuinely required, ask a Developer ADMIN or Platform ADMIN to generate the bill and confirm the Billing period has not ended dialog (Issue early).

3. Why CHECKED and APPROVED Must Be Done by Two Different People (checker ≠ approver) ​

Symptom ​

  • The approval button displays SoD restriction (ติดเงื่อนไข SoD) with a shield-lock icon, or the API returns: Segregation of duties violation: The accounting approver cannot be the same user who performed the technical service check.

Cause ​

WattDee enforces strict Dual Control / Segregation of Duties (SoD):

  1. The user recorded in checkedByServiceUserId (Stage 2) cannot perform Stage 3 final approval (APPROVED) on the same invoice, even if that person holds an ADMIN account with both capabilities.
  2. Invoices also cannot jump directly from DRAFT to APPROVED without passing Stage 2 CHECKED.

Step-by-Step Resolution ​

  1. Have an O&M engineer (SERVICE) or a first administrator perform Stage 2 technical verification (DRAFT → CHECKED).
  2. Have an Accounting user (ACCOUNTING) or a second, different administrator sign in with their own account to perform Stage 3 approval (CHECKED → APPROVED).

4. Locked Billing Periods & Late Intervals (late_intervals) ​

Symptom ​

  • The Dashboard Action Queue alerts that energy arrived after a billing period closed (พลังงานเข้ามาหลังปิดรอบบิล X ไซต์ / Y kWh ยังไม่อยู่ในใบแจ้งหนี้), or re-projecting/swapping meters is blocked for an invoiced month.

Cause ​

  1. Once an invoice moves into CHECKED or APPROVED, its billing period ([billingPeriodStart, billingPeriodEnd)) is locked (Period Lock) so load_profile_15min cannot change underneath an audited or issued invoice.
  2. If HES later backfills missing intervals after a cellular/VPN outage, or modifies interval values inside that locked window, the projection worker refuses to overwrite load_profile_15min and instead stores the new/changed intervals (or withdrawals) in late_intervals, surfaced via GET /api/billing/late-intervals and the Dashboard Action Queue.

Step-by-Step Resolution ​

  1. Inspect the pending unbilled kWh (broken down by TOU period and peak demand) in the Action Queue or /api/billing/late-intervals.
  2. Act based on the invoice status:
    • If CHECKED (not yet APPROVED): Recalculate the draft or return it to DRAFT; pending late_intervals automatically replay into load_profile_15min in the same transaction, then re-check and approve.
    • If already APPROVED: If the unbilled energy warrants correction, Void (REJECTED) the invoice with a reason (automatically replaying late_intervals in the same transaction), then click Reissue to generate a replacement invoice with the recovered telemetry.

5. Why READER and OPERATOR Cannot Open /billing (AccessDenied) & Why READER Cannot See Meter IPs ​

Why /billing Shows AccessDenied ​

Permissions in WattDee follow Organization Tier × Role, never role name alone (see Roles and Permissions):

  • Accessing /billing requires the invoice.view capability.
  • Customer READER (Read only): Holds zero billing capabilities, and is intended strictly for viewing site energy charts and operational meter status.
  • Developer OPERATOR (System operator): Focuses on real-time meter monitoring, test connections (meter.command), network diagnostics (meter.network.read), and alarm triage, not billing.
  • Navigating directly to /billing with either role displays the AccessDenied page (and the Billing link is hidden in the sidebar).

Why READER (and All Customer Users) Cannot See Meter IP Addresses ​

  • Viewing IP addresses, TCP ports, SIM card IDs, and HES gateway error details requires meter.network.read.
  • All customer-tier roles (Customer ADMIN, CUSTOMER, READER), as well as Developer ACCOUNTING, do not have meter.network.read.
  • Both the backend API (stripMeterNetworkFields) and the SPA omit ipAddress, port, simCardId, and gateway lastError from customer responses to protect site network infrastructure.

Resolution ​

Ask your Organization Administrator to assign the appropriate role (CUSTOMER or Customer ADMIN to view and countersign issued invoices; Developer SERVICE/OPERATOR/ADMIN for meter network diagnostics).


6. Sign-In Rate Limit (429 Too Many Requests) & Forgotten Password Reset ​

WattDee login screen where rate-limit and credential errors appear

429 Too Many Requests ("Too many sign-in attempts") ​

  • Cause: In production, BetterAuth enforces an anti-brute-force rate limit of approximately 3 sign-in attempts per 10 seconds per IP address.
  • Resolution:
    1. Wait 10–15 seconds before attempting to sign in again.
    2. Double-check Caps Lock, keyboard layout, and email spelling.
  • Cause: WattDee disables public sign-up (disableSignUp: true) and unauthenticated self-resets to maintain strict multi-tenant security. Account provisioning and password resets are managed by organization administrators.
  • Step-by-Step Admin Password Reset:
    1. Contact your Company Administrator (Customer ADMIN, Developer ADMIN) or Platform Administrator.
    2. The administrator navigates to Settings → Company → People & access, clicks Edit on your user account, and locates Reset password.
    3. The administrator can either enter a policy-compliant password (minimum 8 characters, including uppercase, lowercase, digit, and special character !@#$%&*) or leave the password blank to generate a one-time temporary password, then click Reset password.
    4. Resetting immediately signs the user out of all active sessions. After signing in with the temporary password, open the bottom-left User Menu → Change password to set your own private password.

7. Meter Shows Offline / Communication Lost (VPN & Test Connection Checks) ​

A meter transitions to Offline when no readings arrive for more than 1 hour (60 minutes) or when HES reports commLostAt / verification_failed / inactive. Follow this diagnostic checklist (requires meter.command, meter.network.read, or vpn.manage; see also Meter & Telemetry Guide):

  1. Check HES Activation Status:
    • Under Settings → Site → Meters, verify the meter is active (isActive = true) and HES status is HES is polling (active) rather than Disabled in HES or verification pending. Remember that testing or editing does not automatically activate HES polling. Use Activate in HES when ready.
  2. Verify Managed VPN Tunnel (if using VPN (Mikrotik)):
    • Ask a Platform ADMIN to open Settings → Developer Company → VPN profiles and click Refresh status.
    • Confirm the VPN status tag reads Tunnel established (tunnel_up) rather than controller_offline, runner_error, pending, or disabled.
    • Confirm the meter is assigned to the correct VPN profile and its IP address falls within allowed_ips.
  3. Run Test connection:
    • Open the meter's Diagnostics panel (/meter side panel or Settings → Site → Meters) and click Test connection. Review the returned diagnostic:
      • config_error / missing LLS password: Configure the DLMS LLS password on the HES host and restart HES.
      • auth_failed: The meter rejected the LLS password; verify the HES host secret matches the physical meter.
      • operation was canceled / session timeout: TCP connected, but the meter did not answer; usually an interface mismatch between HDLC (4G modem / serial converter) and WRAPPER (direct Ethernet LAN on the meter).
      • connect_failed / poll_timeout: Unreachable IP/port (default 4059); inspect site power, 4G/APN SIM, Mikrotik VPN tunnel, and firewall rules.
      • protocol_error: Verify the configured meter model (Saral 305, Premier 550, Prometer 100) and interface.
  4. Recover Outage Gaps:
    • Once Test connection succeeds, click Read now or trigger a Backfill (up to 31 days per request) to pull stored 15-minute intervals from the meter's internal memory.

8. Using WattDee Docs with AI Assistants & Agents ​

The bilingual WattDee User Manual is published at https://docs.wattdee.com and provides three AI-native integration paths:

InterfaceURL / CommandBest For
/llms.txt Indexhttps://docs.wattdee.com/llms.txtLightweight structured index of every Thai and English manual page with summaries for fast LLM discovery
/llms-full.txt Bundlehttps://docs.wattdee.com/llms-full.txtComplete plain-Markdown bundle of both languages for one-shot context injection or RAG indexing (per-language bundles are also published at /th/llms-full.txt and /en/llms-full.txt)
Local MCP Serverbun run docs:mcpExposes WattDee documentation directly to MCP-capable AI clients (Claude Desktop, Cursor, Antigravity) with search_wattdee_manual, get_wattdee_guide, and get_role_capabilities

Running the docs:mcp MCP Server ​

From the root of the AMR repository, launch the documentation MCP server with:

bash
bun run docs:mcp

Or register it in your MCP client configuration (replacing /path/to/AMR with your local repository path):

json
{
  "mcpServers": {
    "wattdee-docs": {
      "command": "bun",
      "args": ["run", "docs:mcp"],
      "cwd": "/path/to/AMR"
    }
  }
}

Example Questions to Ask Your AI Assistant

  • "Walk me through the WattDee PPA discount and 7% VAT rounding steps with an example."
  • "Why does a Customer READER or Developer OPERATOR hit AccessDenied on /billing?"
  • "How do I replay late_intervals after voiding an APPROVED invoice?"

WattDee AMR & Private PPA Billing User Manual