Troubleshooting & FAQs

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• QUICKSTART.md
• CLOUDFLARE_DEPLOY.md
• GITHUB_PUSH.md
• AGENT.md
• rust-terminal/BUILD.md
• rust-terminal/src/main.rs

This page provides a comprehensive guide to identifying and resolving common issues encountered during the setup, deployment, and operation of the WIREDUP system. It covers the Python AI Auto-Wiring engine, the NexTerm Rust terminal, and web deployment via Cloudflare Pages.

The scope of this document includes dependency resolution, environment configuration, cross-language integration (Rust-Python bridge), and git-based deployment workflows.

Deployment Troubleshooting

Deploying WIREDUP involves syncing code to GitHub and hosting the web interface on Cloudflare Pages. Issues typically arise from authentication failures or misconfigured build settings.

Cloudflare Pages Issues

Common failures during Cloudflare deployment often relate to incorrect directory paths or API token permissions.

Problem	Cause	Solution
Build fails	Incorrect output directory	Ensure "Build output directory" is set to public.
404 Not Found	Missing index file	Verify public/index.html exists in the repository.
Auth Failed	Expired/Invalid token	Reconnect GitHub or regenerate the Wrangler API token.
Changes not appearing	Deployment delay	Check the Cloudflare Pages dashboard for deployment status.

Sources: QUICKSTART.md:123-133, CLOUDFLARE_DEPLOY.md:73-83

GitHub Authentication & Push Errors

When pushing code manually, authentication is the most frequent point of failure.

Common Git Errors:

• Authentication Failed: Ensure you are using a Personal Access Token (PAT) with repo scope rather than your GitHub password.
• Permission Denied: Verify the SSH key is added to your GitHub account settings.
• Repository Not Found: Check for typos in the remote URL: `https://github.com/RemyLoveLogicAI/WIREDUP.git%60.

Sources: GITHUB_PUSH.md:78-90, GITHUB_PUSH.md:10-38

NexTerm (Rust Terminal) Troubleshooting

The NexTerm terminal relies on a successful build environment and a functional bridge to the Python Auto-Wiring system.

Build and Runtime Failures

If the Rust compiler or the runtime environment fails, follow these steps:

• Undeclared Crate: Run cargo clean && cargo build to refresh dependencies.
• Linking with 'cc' failed: Install build essentials (e.g., build-essential on Ubuntu or Xcode Tools on macOS).
• Python Not Found: Ensure Python 3.8+ is installed and accessible in the system path.

Sources: rust-terminal/BUILD.md:118-132, rust-terminal/BUILD.md:5-10

AI Auto-Wiring Integration

NexTerm integrates with Python via a bridge that requires specific environment variables and directory structures.

Auto-wiring Connection Issues:

1. Variable not set: Run export NEXTERM_AUTOWIRE=true before launching the terminal.
2. Pathing: Ensure the Rust terminal is in a sibling directory to the Python src folder (e.g., project/src and project/rust-terminal).
3. Import Errors: If the bridge fails, NexTerm logs the Python stderr. Check if requirements.txt dependencies are installed.

Sources: rust-terminal/src/main.rs:60-95, rust-terminal/BUILD.md:95-108

AI Agent & Auto-Wiring FAQs

Why is my agent not registered?

Agents must be registered with the AutoWire engine before they can be resolved. Check if the agent class is decorated with @autowire.register_decorator or manually added via autowire.register().

Sources: AGENT.md:90-112

How do I handle circular dependencies?

The Auto-Wiring engine includes circular detection. If a circular dependency is detected, the engine will raise an error during the resolution phase. To fix this, refactor shared logic into a separate service or use a different injection scope.

Sources: public/index.html:152-155, AGENT.md:275-278

Configuration Not Loading

The system searches multiple sources for configuration. If your settings aren't applied:

• Verify the .env file exists and uses the AI_ prefix for system variables.
• Check the naming convention: AI_AGENTS_[NAME]_[KEY].
• Ensure the ConfigLoader is initialized via python -m src.cli init.

Sources: README.md:90-110, AGENT.md:150-165

Summary of Key Commands

Task	Command
Check Sync Status	git log --oneline origin/main..HEAD
Deploy (CLI)	npx wrangler pages deploy public --project-name=wiredup
Init Python Config	python -m src.cli init
Build NexTerm	cargo build --release
Verify Python Bridge	python3 -c "from src.core.autowire import get_autowire; print(get_autowire())"

Sources: QUICKSTART.md:73-85, GITHUB_PUSH.md:100-110, DEPLOYMENT.md:32-35

The WIREDUP system is designed for high reliability, but its cross-language nature (Rust/Python) and cloud-native deployment (Cloudflare) require correct environment setup and authentication to function effectively. By following the troubleshooting steps above, most connectivity and build issues can be resolved quickly.