FAQ and troubleshooting

This guide collects real issues, edge cases, and resolutions encountered across our launch rehearsals (L-01 / #102) and production testing.

---

1. Account, Login & Organisation

Why can’t I see my team’s organisation after signing in?

Cause: You signed up with a personal email address (e.g., @gmail.com) instead of your corporate email domain, or your email domain has not yet been linked to an existing company workspace. Resolution:

1. Check your email address in Settings › Profile.
2. If you used a personal address, sign out and register using your work email (e.g., you@company.com).
3. If your company already has an organisation, an administrator must approve your join request or invite you via Organization › Members (/organization).

Why do I see “No organisation access” on certain platform routes?

Cause: Some advanced features (such as custom LLM gateways or enterprise telemetry) require company organisation membership. Resolution: Navigate to /onboarding to either create a new company organisation or submit an access request to your company’s administrator.

---

2. TeksPlan

Why does TeksPlan ask me repeated or similar questions?

Cause: The 7-specialist panel detected competing constraints in your problem statement (e.g. asking for “zero external services” while simultaneously asking for “OAuth with 5 external social providers”). Resolution: Choose one of the recommended multiple-choice options or type a explicit directive in the response box:

“Prioritize zero external services: use simple email-and-password sessions in SQLite instead of third-party OAuth.”

Can I change the technology stack after a plan is approved?

Cause: An approved plan locks its architecture contracts so TeksBuild has a stable specification to build against. Resolution: In your project dashboard, click Request Changes. In the prompt box, specify:

“Revise tech stack: switch from Python FastAPI to Node.js TypeScript with Express.” The planner will generate Plan v2 while preserving your data models and requirements.

---

3. TeksBuild

My preview sandbox timed out or shows a white screen. What should I do?

Cause: The application may have hit an unhandled exception during server-side startup, or the port binding failed. Resolution:

1. In the build card, click View Sandbox Logs.
2. Check for missing environment variables or fatal runtime exceptions.
3. Click Restart Sandbox to boot a fresh container.

A build failed with “pnpm install: Tarball download timeout”

Cause: A transient upstream network hiccup with the npm registry during container provisioning. Resolution: Click Re-run Build. TeksBuild uses a local package cache for secondary attempts.

How do I revert a code change that caused regressions?

Resolution: Every build creates an atomic git commit. On the review page (/projects/[id]/review), click Revert Commit. TeksBuild generates an inverse diff and runs the automated test suite to ensure the revert is clean.

---

4. Connect GitHub & Vercel

GitHub App says “Resource not accessible by integration”

Cause: The repository you selected requires organization administrator approval, or branch protection rules prohibit automated pushes to main. Resolution:

• Ask your GitHub Organization Owner to approve the Tekspaz GitHub App.
• Configure TeksBuild to target a feature branch (e.g. tekspaz/preview) instead of pushing directly to protected branches.

Vercel deployment fails with “Invalid Token”

Cause: The Vercel access token has expired or was created without permission for the target Team. Resolution: Generate a new personal access token at vercel.com/account/tokens with Team Scope matching your Vercel Team ID, then re-enter it under Settings › Connections.

---

5. TeksInfra

The InfraOps worker shows “Disconnected” in TeksInfra

Cause: The background systemd daemon stopped, or outbound HTTPS traffic to teks1platform.tekspaz.ai is blocked by an egress firewall. Resolution:

1. Check daemon status on your server:

   sudo systemctl status infraops-worker

2. View service logs:

   sudo journalctl -u infraops-worker -n 50 --no-pager

3. Test connectivity to the platform:

   curl -I https://teks1platform.tekspaz.ai/api/health

4. Restart the worker:

   sudo systemctl restart infraops-worker

Why did Airflow task failures not trigger an incident?

Cause: The Airflow on_failure_callback is either not mounted on the failing DAG, or the worker’s intake port (8085) is unreachable from the Airflow execution environment. Resolution: Run a manual curl test from the Airflow worker node:

curl -X POST http://127.0.0.1:8085/v1/airflow/events \
  -H "Content-Type: application/json" \
  -d '{"dag_id":"test_dag","task_id":"test_task","exception":"test alert"}'

Check if the test event appears in TeksInfra › Activity.

---

6. TeksOptima

When connecting Snowflake, I get “That isn’t a TeksOptima read token”

Cause: The token was copied incorrectly or did not originate from the SNOWFLAKE.ML.GENERATE_TELEMETRY_TOKEN procedure. Resolution: TeksOptima read tokens always start with the prefix tksr_. Ensure there are no leading or trailing whitespace characters when pasting the token.

Why is Snowflake warehouse spend showing 0 credits?

Cause: Snowflake’s SNOWFLAKE.ACCOUNT_USAGE schema updates asynchronously with a 45–90 minute latency from Snowflake’s internal metering pipeline. Resolution: Wait up to 1 hour after generating query load. For real-time active warehouse status, TeksOptima queries INFORMATION_SCHEMA.WAREHOUSES directly.

---

7. CLI & API

Running pnpm rigs whoami returns “404 invalid_request”. Is my token broken?

No, your token is working perfectly! whoami deliberately sends a probe envelope ID (env-connectivity-probe). If your credentials pass all authentication and policy gates, the service returns 404 invalid_request because the envelope does not exist. If your credentials were invalid, you would receive 401 Unauthorized or 403 Forbidden.

How can I run CLI commands behind a corporate proxy?

Resolution: Set the standard HTTPS_PROXY environment variable before invoking pnpm:

HTTPS_PROXY="http://proxy.internal:8080" pnpm rigs health

---

8. Contacting Support

If you encounter an issue not resolved here:

• Email Support: sales@tekspaz.com (4-hour SLA during launch week)
• Live Rehearsal Assistance: Reach out directly to your assigned on-call engineering lead.
• Incident Escalation: For P0 launch blockers, ping @KaviyaSree2703, @harivarsan10, @prithivi-tekspaz, or @sanjay-tekspaz in the issue discussion.