oliver-kriska/claude-elixir-phoenix / targets/pi/skills/elixir-idioms
elixir-idioms
VerifiedOTP/BEAM patterns and Elixir idioms — GenServer, Supervisor, Task, Registry, pattern matching, with chains, pipes. Use when designing processes or debugging BEAM issues.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.6 KB |
| references/anti-patterns.md | markdown | 4.6 KB |
| references/elixir-118-features.md | markdown | 3.6 KB |
| references/elixir-120-type-system.md | markdown | 5.9 KB |
| references/error-handling.md | markdown | 2.7 KB |
| references/mix-tasks.md | markdown | 2.9 KB |
| references/otp-patterns.md | markdown | 10.6 KB |
| references/pattern-matching.md | markdown | 1.9 KB |
| references/troubleshooting.md | markdown | 4.5 KB |
| references/with-and-pipes.md | markdown | 7.2 KB |
references/troubleshooting.md
View on GitHub# BEAM Troubleshooting Playbook
Production debugging for Phoenix/BEAM applications. For code bugs, see `deep-bug-investigator` agent.
## Quick Diagnosis
| Symptom | Likely Cause | Section |
|---------|--------------|---------|
| High memory, growing | Process leak, ETS bloat | Memory Issues |
| Slow responses | N+1, GenServer bottleneck | Performance |
| Random crashes | Unhandled errors, supervisor | Crashes |
| Timeouts | DB pool, GenServer call | Timeouts |
| Node unresponsive | Scheduler block, long GC | BEAM Issues |
## Memory Issues
### With Tidewave
```elixir
# Top memory processes
mcp__tidewave__project_eval """
Process.list()
|> Enum.map(fn pid -> {pid, Process.info(pid, :memory)} end)
|> Enum.filter(fn {_, mem} -> mem != nil end)
|> Enum.map(fn {pid, {:memory, mem}} -> {pid, mem} end)
|> Enum.sort_by(&elem(&1, 1), :desc)
|> Enum.take(10)
|> Enum.map(fn {pid, mem} ->
info = Process.info(pid, [:registered_name, :current_function])
{info[:registered_name] || pid, div(mem, 1024), info[:current_function]}
end)
"""
# ETS table sizes
mcp__tidewave__project_eval """
:ets.all()
|> Enum.map(fn t -> {t, :ets.info(t, :memory) * :erlang.system_info(:wordsize)} end)
|> Enum.sort_by(&elem(&1, 1), :desc)
|> Enum.take(10)
|> Enum.map(fn {t, mem} -> {t, div(mem, 1024)} end)
"""
```
### Without Tidewave
```bash
# Attach to running node
iex --sname debug --remsh myapp@hostname
# In IEx
:observer.start()
```
### Common Causes
1. **LiveView socket assigns** - Use `temporary_assigns` or streams
2. **ETS table growth** - Check for missing cleanup
3. **Process mailbox** - GenServer not keeping up
4. **Binary memory** - Large binaries not GC'd (use `:binary.copy/1`)
## Performance Issues
### N+1 Query Detection
```elixir
# config/dev.exs - log slow queries
config :my_app, MyApp.Repo,
log: :debug,
stacktrace: true
```
### GenServer Bottleneck
```elixir
mcp__tidewave__project_eval """
pid = Process.whereis(MyApp.SomeServer)
{:message_queue_len, len} = Process.info(pid, :message_queue_len)
IO.puts("Queue length: \#{len}") # >100 = problem
"""
```
**Signs:**
- Message queue growing
- Call timeouts
- Single process high CPU
**Solutions:**
- Pool of workers (Poolboy)
- ETS for read-heavy (GenServer writes, ETS reads)
- Partition by key (Registry + DynamicSupervisor)
### Slow Ecto Queries
```sql
-- With Tidewave
mcp__tidewave__execute_sql_query """
SELECT query, calls, mean_time, total_time
FROM pg_stat_statements
ORDER BY mean_time DESC
LIMIT 10
"""
-- Missing indexes
mcp__tidewave__execute_sql_query """
SELECT relname, seq_scan, idx_scan
FROM pg_stat_user_tables
WHERE seq_scan > idx_scan
ORDER BY seq_scan DESC
"""
```
## Crashes
### Common Crash Patterns
| Error | Cause | Fix |
|-------|-------|-----|
| `noproc` | Process died/not started | Check supervisor, handle `{:error, _}` |
| `timeout` | GenServer.call timeout | Increase timeout or use cast |
| `badmatch` | Pattern match failed | Add catch-all clause |
| `function_clause` | No matching function | Check guards, add fallback |
| `badarg` | Wrong argument type | Validate input |
### Supervisor Tree Analysis
```elixir
mcp__tidewave__project_eval """
Supervisor.which_children(MyApp.Supervisor)
|> Enum.map(fn {id, pid, type, _} ->
%{id: id, pid: pid, type: type}
end)
"""
```
## Timeouts
### DB Pool Exhaustion
**Symptoms:** Random timeouts, "connection not available"
**Check:**
```elixir
# Current pool size
Application.get_env(:my_app, MyApp.Repo)[:pool_size]
```
**Solutions:**
- Increase `pool_size`
- Add `queue_target` and `queue_interval`
- Find long-running queries
- Use `Repo.checkout/1` properly for transactions
### GenServer Call Timeout
```elixir
# Default is 5000ms
GenServer.call(pid, :request, 10_000) # Increase if needed
# Or use cast + handle_info for async
GenServer.cast(pid, {:request, self()})
```
## BEAM Issues
### Scheduler Utilization
```elixir
mcp__tidewave__project_eval """
:scheduler.utilization(1000) # Sample for 1 second
"""
```
### Long GC Pauses
```elixir
# Enable GC logging
:erlang.system_flag(:long_gc, 50) # Log GC > 50ms
```
### Dirty Schedulers Blocked
```elixir
mcp__tidewave__project_eval """
:erlang.statistics(:dirty_cpu_run_queue_lengths)
"""
```
## Quick Checklist
```markdown
## Troubleshooting: [Issue]
### Symptoms
- [ ] High memory?
- [ ] Slow responses?
- [ ] Timeouts?
- [ ] Crashes?
### Checked
- [ ] Logs: `mcp__tidewave__get_logs level: :error`
- [ ] Memory: Top processes
- [ ] Queries: Slow query log
- [ ] Processes: GenServer queue lengths
### Root Cause
[...]
### Fix
[...]
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |