Skip to content
Alkami Developer Portal Docs

Troubleshooting

🛠️ Troubleshooting Guide

Section titled “🛠️ Troubleshooting Guide”

Running into hiccups? Don’t worry — we’ve got your back. Below are the most common issues developers face during the hackathon, along with quick fixes to get you back on track.

🚧 Common Networking & Environment Issues

Section titled “🚧 Common Networking & Environment Issues”

“It worked at home but not here.” Development environments can behave differently depending on corporate policies, VPNs, proxies, or firewalls.

  1. Are you behind a corporate firewall or proxy? Try switching to a personal/hotspot connection to test if your access is being blocked.
  2. Try accessing the following tools:
  3. If these are inaccessible, contact your network admin or try using a VPN.
  4. Disable strict antivirus/endpoint security tools temporarily during development.
  5. You have an Alkamist — work with them to see what might be the issue.

🧪 SDK Setup Not Working?

Section titled “🧪 SDK Setup Not Working?”

Make sure you followed all steps on the Merlin install guide.

  1. Confirm that Merlin is installed and accessible from your terminal or command prompt.
  2. If Merlin is not installing or starting, verify your machine meets the minimum requirements:
    • Memory: At least 8GB RAM recommended.
    • CPU: Minimum 4 cores recommended.
  3. Check your machine permissions and policies — some corporate or personal settings may block software installation or network calls. If unsure, contact your IT or try on a different machine.
  4. Refer to the detailed Merlin Troubleshooting guide for common install issues.
  5. Make sure your SDK version is up to date. Use merlin upgrade if you have Merlin installed.
  6. You have an Alkamist — work with them to help identify any environment-specific blockers.

🔐 API Access Problems?

Section titled “🔐 API Access Problems?”

If your API calls are failing or you’re getting authentication or connectivity errors, here are the most common things to check:

  1. Confirm your API key is active and correctly copied.
  2. Verify you are sending the API key correctly, usually in the Authorization header as Bearer <your_api_key>.
  3. Use Postman to test your API calls and verify the requests and responses.
  4. Check your network and firewall settings — corporate policies or VPNs may block outgoing requests.
  5. Make sure your machine’s date and time are accurate — time skew can cause authentication failures.
  6. Look out for rate limits or throttling errors (usually HTTP 429). If you hit rate limits, slow down your requests or wait before retrying.
  7. Review the response error messages carefully; they often contain clues about what went wrong.
  8. You have an Alkamist — work with them to troubleshoot API access or key issues.

Tip: If you receive unexpected errors, double-check your API key is entered correctly and that your account has the necessary permissions.

🔄 Something Just Isn’t Working?

Section titled “🔄 Something Just Isn’t Working?”

Sometimes it’s not you — it’s the setup. Here’s a checklist of other common “gotchas”:

  • ✅ You’ve restarted your development server after installing dependencies
  • ✅ You’ve cleared your browser cache
  • ✅ You’re not using a restricted guest WiFi network
  • ✅ You’re running Node.js LTS (≥ v18 recommended)
  • ✅ You’ve updated to the latest SDK or tooling versions

🧭 Where to Get Help

Section titled “🧭 Where to Get Help”
🔗 Join Slack Support Chat with Alkamists, mentors, and other devs. Quickest way to get unblocked.
🧠 Developer Docs Everything you need to get going with SDK, APIs, and deployment.
💻 GitHub Repo Star, fork, or raise issues directly in the Hackathon repo.

✅ You’re Not Alone

Section titled “✅ You’re Not Alone”

Every developer hits snags — especially in a high-energy hackathon. Take a breath, ask questions, and keep building.

You’ve got this. 🚀