Fix Go "Assignment Mismatch" and "Multiple-Value in Single-Value Context" Errors
A Go function that returns two values hands back a pair, not a single thing that can be split up later — and the compiler counts. Give the pair one variable and the build stops with an assignment mismatch; drop the pair into an arithmetic expression and it stops again, with a different message. This guide reproduces both errors exactly as the compiler prints them, states the counting rule that produces them, and maps the exceptions that surround it — the call shapes where several values may legally land, and the built-in operations whose value count changes with the number of variables waiting to receive them.
Written November 18, 2026 · Tested with Go 1.26.4 · 26 min read
- The first error: one variable, two values
- Too many variables is the same error
- The direct fixes: bind both, or blank one
- The exact rule: tuple assignment
What this guide is
Go functions and methods can return multiple values — a result and an error is the famous pair, but any count is allowed. The values come back together, as one multi-valued operation, and they can only land in places that are built to receive that many values at once. When the receiving side has the wrong count, the compiler stops the build with one of two messages. An assignment whose left side names too few or too many variables earns an assignment mismatch. A multi-valued call placed where a single value belongs — inside an arithmetic expression, or in a condition — earns multiple-value ... in single-value context. The examples here use Go 1.26.4. Every example lives in a single file named main.go inside one module, created once from an empty directory:
$ mkdir counts
$ cd counts
$ go mod init example.com/counts
go: creating new go.mod: module example.com/counts
Each program that follows replaces the contents of that main.go. Two functions recur throughout: pair, which returns two int values, and single, which returns one. Most of the errors below are pair meeting a receiving side that was counted wrong — and the message, read carefully, already contains the whole diagnosis, because it states both counts.
The first error: one variable, two values
The smallest program that earns the assignment mismatch asks one variable to receive a two-value call:
// main.go
package main
func pair() (int, int) {
return 1, 2
}
func main() {
x := pair()
_ = x
}
$ go build
# example.com/counts
./main.go:8:7: assignment mismatch: 1 variable but pair returns 2 values
Read the message in its parts. The position, ./main.go:8:7, is the call on line 8 — column 7 is where pair begins — not the variable, which sits earlier on the same line. The wording then gives both counts in one breath: 1 variable on the left, pair returns 2 values on the right, with the function named, so in a program with several calls the message says which call overflowed. The _ = x line under the declaration changes nothing about this error; it is there so the unused-variable error stays out of the way and the count error stands alone.
The point the message is making is that there is no such thing as receiving "the pair" in one variable. A multi-valued call is not a single value of some pair type that x could hold and unpack later. The two values exist only at the moment of the call, and each one needs its own receiving variable at that moment. One variable is one slot, and two values do not fit in one slot.
Too many variables is the same error
The mismatch is a count check, not a one-direction overflow check, and it fires just as readily when the left side asks for more than the call returns:
// main.go
package main
func pair() (int, int) {
return 1, 2
}
func main() {
a, b, c := pair()
_, _, _ = a, b, c
}
$ go build
# example.com/counts
./main.go:8:13: assignment mismatch: 3 variables but pair returns 2 values
Three variables, two values: the third variable has nothing to receive, and the compiler says so with the same sentence shape, counts reversed. The position moved to column 13 — still the call, now pushed right by the longer variable list in front of it. Nothing is special about the direction. The rule underneath both programs is exact equality: the number of variables must match the number of values, and any difference in either direction is this error.
The same shape appears when the call returns fewer values than a programmer expects, which is the common real-world cause: a function whose signature changed, or one that was never multi-valued to begin with. Here single returns one value and the declaration asks for two:
// main.go
package main
func single() int {
return 7
}
func main() {
a, b := single()
_, _ = a, b
}
$ go build
# example.com/counts
./main.go:8:10: assignment mismatch: 2 variables but single returns 1 value
The message names single and counts its returns as 1 value — singular, where the pair messages said 2 values. That naming is the diagnostic gift of this error family: when the mismatch appears in real code, the function named in the message is the one whose return list disagrees with the variables in front of it, and comparing those two lists — the signature against the declaration — settles which side was written against the wrong assumption.
The direct fixes: bind both, or blank one
When the count is the only problem, the fixes are as mechanical as the error. Binding every value the call returns makes the first program build and run:
// main.go
package main
import "fmt"
func pair() (int, int) {
return 1, 2
}
func main() {
a, b := pair()
fmt.Println(a, b)
}
$ go run main.go
1 2
When one of the values is genuinely unwanted, the blank identifier takes its slot at the declaration, exactly as it does for any unwanted half of a two-value operation:
// main.go
package main
import "fmt"
func pair() (int, int) {
return 1, 2
}
func main() {
a, _ := pair()
fmt.Println(a)
}
$ go run main.go
1
Writing a, _ := pair() is the correct shape of this fix, and the alternative shapes are worth ruling out explicitly, because each is a first guess that fails. Declaring one variable and discarding afterward is impossible — the mismatch happens at the declaration itself, before any later line can help. Wrapping the call, converting it, or assigning it through an intermediate variable all run into the second error in this guide, because every one of those places is a single-value context. The values can only be received whole, at an assignment-shaped place, with the right number of names.
The exact rule: tuple assignment
The specification states the rule as a property of assignment statements. A tuple assignment assigns the individual elements of a multi-valued operation to a list of variables, and it comes in two forms. In the first form, the right-hand operand is a single multi-valued expression — a function call, a channel or map operation, or a type assertion — and the number of operands on the left must match the number of values that operation produces. In the second form, the right side is a list of expressions, the number of operands on the left must equal the number of expressions on the right, each expression must be single-valued, and the values are assigned one to one, in order.
Every error so far is the first form failing its count. x := pair() is a tuple assignment whose single right-hand operation produces two values for one left-hand operand. a, b, c := pair() is the same form with three operands for two values. The short declaration := makes no difference to any of this — it is shorthand for a variable declaration with initializers, and the same counting applies to a plain assignment to variables declared earlier:
// main.go
package main
func pair() (int, int) {
return 1, 2
}
func main() {
var a int
a = pair()
_ = a
}
$ go build
# example.com/counts
./main.go:9:6: assignment mismatch: 1 variable but pair returns 2 values
Same message, same counts — the error belongs to the assignment, not to the declaration keyword. And the matching plain assignment, with both variables declared first, is the ordinary way to receive a pair into variables that already exist:
// main.go
package main
import "fmt"
func pair() (int, int) {
return 1, 2
}
func main() {
var a, b int
a, b = pair()
fmt.Println(a, b)
}
$ go run main.go
1 2
The second error: a pair where one value belongs
An assignment is not the only place a call can appear, and the other places are built for exactly one value. Putting a two-value call inside an arithmetic expression asks the expression to compute with a pair, and the compiler refuses with the second message of this guide:
// main.go
package main
func pair() (int, int) {
return 1, 2
}
func main() {
y := pair() * 2
_ = y
}
$ go build
# example.com/counts
./main.go:8:7: multiple-value pair() (value of type (int, int)) in single-value context
The message is longer because it has more to explain. It names the call, states what the call amounts to when something tries to treat it as one value — value of type (int, int), a pair of types in parentheses — and names the offense: that pair was used in a single-value context. The position is the call itself, column 7 again. There is no version of this program that computes what a hurried reader might expect — no doubling of both values, no taking of the first — because a multi-valued call is not an expression that yields a value an operator can consume. It yields values, plural, and only assignment-shaped places can receive them.
A condition is the same kind of place. An if condition is one boolean expression, and a two-value call inside it earns the identical message:
// main.go
package main
import "fmt"
func pair() (int, int) {
return 1, 2
}
func main() {
if pair() == 1 {
fmt.Println("x")
}
}
$ go build
# example.com/counts
./main.go:10:5: multiple-value pair() (value of type (int, int)) in single-value context
The comparison does not rescue the call by singling out its first value — Go has no first-value convention to fall back on. Anywhere a single expression is expected — an operand, a condition, a function argument in the ordinary position-by-position sense, a return value in a function that returns one value — a multi-valued call is this error. The two exceptions that follow are real, but they are exceptions of shape, not of convenience: in each, the receiving side is itself built from a matching list of slots.
Exception one: passing a call straight through
The specification carves out one call shape in which a multi-valued call may appear as an argument. If the return values of a function g are equal in number and individually assignable to the parameters of another function f, then the call f(g()) invokes f with g's return values passed to its parameters in order. The call to f must contain no arguments other than the call to g. Both halves of that rule are visible in one program — a two-parameter function receiving pair whole, and a two-result function whose entire return is pair:
// main.go
package main
import "fmt"
func pair() (int, int) {
return 1, 2
}
func show(a int, b int) {
fmt.Println(a, b)
}
func pass() (int, int) {
return pair()
}
func main() {
show(pair())
a, b := pass()
fmt.Println(a, b)
}
$ go run main.go
1 2
1 2
show(pair()) is not show receiving a pair as one argument; it is show receiving two arguments, supplied by the call. The return statement in pass works the same way from the other side: a function with a result list may return a single multi-valued call whose results match that list in number and assignability, instead of listing each value as its own expression. These pass-through forms are the idiomatic way to forward a result-and-error pair — or any pair — without naming its halves, and they are the reason a multi-valued call sometimes appears to behave like a value: it never becomes one, it is unpacked directly into the next list of slots.
The pass-through reaches one step further when the receiving function is variadic. If f has a final variadic parameter, the return values of g that remain after the regular parameters are assigned go to that variadic parameter — which is why the standard printing call accepts a multi-valued call whole:
// main.go
package main
import "fmt"
func pair() (int, int) {
return 1, 2
}
func main() {
fmt.Println(pair())
}
$ go run main.go
1 2
fmt.Println has only a variadic parameter, so both of pair's values land in it, and the output is the two values side by side. This is a consequence of the same special case, not a separate printing feature — and its boundary is the same as the boundary of the ordinary pass-through: the multi-valued call must be the whole argument list. A call that mixes pair() with arguments of its own is an ordinary call, and pair() inside it is back in a single-value context.
Exception two: a call as a statement discards its values
One more place receives any number of return values without counting them: nowhere. A function call used as a statement — the call standing alone as its own line, for whatever side effects it has — discards its return values entirely, and the compiler asks for no variables at all:
// main.go
package main
func pair() (int, int) {
return 1, 2
}
func main() {
pair()
}
$ go build
The build succeeds with no output. Calls may appear in statement context, and a call whose results nobody needs is legal exactly as written. The same discarding is available inside an assignment when the discard is the deliberate point, by giving every value to the blank identifier:
// main.go
package main
func pair() (int, int) {
return 1, 2
}
func main() {
_, _ = pair()
}
$ go build
Both forms state that the values are unwanted; they differ in what they claim. The bare statement says the call was made for its effect and its results were never the point. The blank assignment says the results were received and thrown away on purpose, which is the right shape when the call sits inside a larger assignment pattern. What neither form does is make the values available later — a discarded value is gone, and code that turns out to need it has to call again or bind it properly.
The built-in two-value forms
Function calls are not the only multi-valued operations. Three built-in operations each yield one value in their ordinary form and two values in a special assignment form, and the second value is always the same kind of report: whether the first value is real. A map index yields the stored value alone, or the value plus a boolean that reports whether the key was present:
// main.go
package main
import "fmt"
func main() {
m := map[string]int{"one": 1}
v, ok := m["two"]
fmt.Println(v, ok)
}
$ go run main.go
0 false
The key "two" is absent, so v receives the element type's zero value and ok reports false — the pair is what separates "absent" from "present with a zero value", a distinction the one-value form, which prints the same 0 for both, cannot make. A type assertion has the same two forms: asserted alone it panics when the assertion fails, while the two-value form reports failure in the boolean instead:
// main.go
package main
import "fmt"
func main() {
var i any = 1
v, ok := i.(int)
fmt.Println(v, ok)
s, ok2 := i.(string)
fmt.Println(s, ok2)
}
$ go run main.go
1 true
false
The first assertion holds — i holds an int — and prints 1 true. The second fails, so s receives the zero value for string, which is empty, and ok2 reports false; the second output line is that empty string, a space, and false. A channel receive completes the set: its two-value form reports whether the received value was sent before the channel was closed, which is how a receiving loop tells drained-and-closed from one more value:
// main.go
package main
import "fmt"
func main() {
ch := make(chan int, 1)
ch <- 9
close(ch)
v, ok := <-ch
fmt.Println(v, ok)
v2, ok2 := <-ch
fmt.Println(v2, ok2)
}
$ go run main.go
9 true
0 false
The first receive takes the value that was sent before the close and reports true. The second finds the channel empty and closed, receives the zero value at once rather than blocking, and reports false. In all three operations the pattern is identical: one variable receives the ordinary one-value form, two variables receive the value plus the report, and the choice is made by the count on the left side of the assignment — the operation itself does not change.
That flexibility has a hard edge, and it is the assignment mismatch again, in its plainest wording. Asking any of these operations for three values fails, because none of them has a three-value form:
// main.go
package main
func main() {
m := map[string]int{"one": 1}
a, b, c := m["one"]
_, _, _ = a, b, c
}
$ go build
# example.com/counts
./main.go:5:13: assignment mismatch: 3 variables but 1 value
// main.go
package main
func main() {
var i any = 1
a, b, c := i.(int)
_, _, _ = a, b, c
}
$ go build
# example.com/counts
./main.go:5:13: assignment mismatch: 3 variables but 1 value
// main.go
package main
func main() {
ch := make(chan int, 1)
ch <- 9
a, b, c := <-ch
_, _, _ = a, b, c
}
$ go build
# example.com/counts
./main.go:6:13: assignment mismatch: 3 variables but 1 value
All three messages are identical apart from the position, and all three count the operation as 1 value — not two. The two-value form exists only as the special assignment form the specification defines for exactly two receivers; it is not a count the operation carries into other contexts. Ask for one variable and the operation is single-valued; ask for two and the special form applies; ask for three and the compiler falls back to the operation's ordinary count, one, and reports the mismatch against it. The position, column 13 in each program, is the operation itself — the index, the assertion, the receive — just as the call position was in the function examples.
The mixed-list trap
a, b, c := pair(), 3 as three values for three variables — two from the call, one from the literal. The compiler does not read it that way:// main.go
package main
func pair() (int, int) {
return 1, 2
}
func main() {
a, b, c := pair(), 3
_, _, _ = a, b, c
}
$ go build
# example.com/counts
./main.go:8:13: assignment mismatch: 3 variables but 2 values
The counts in the message are the tell. The right side is reported as 2 values — not three. Under the tuple rule's second form, a right side with more than one expression is a list of single-valued expressions, counted one per expression: pair() occupies one entry in that list and 3 occupies the other, so the list has two entries for three variables. A multi-valued operation expands to fill several variables only in the first form, where it stands alone on the right side; beside another expression it does not expand at all, and the assignment fails on the entry count before any question of types arises.
The mirror image confirms the reading. A single-valued call in a mixed list is an ordinary single-valued expression, and the same shape with single in place of pair compiles without complaint:
// main.go
package main
func single() int {
return 7
}
func main() {
a, b := single(), 3
_, _ = a, b
}
$ go build
Two expressions, two variables, each expression single-valued — the second form is satisfied. So the practical rule for mixed assignments is simple: a multi-valued call must be the only thing on its right side, or its values must be bound in their own assignment first and then combined as ordinary variables. Splitting the failing program into two assignments — a, b := pair() and then c := 3 — is not a workaround for a compiler quirk; it is the shape the rule describes.
Neighboring count checks with different messages
Two nearby places count values too, and each has its own message, so a count error's wording identifies which check caught it. A call's arguments are counted against the callee's parameters, and a shortfall is reported with a pair of have and want lines under the main message:
// main.go
package main
import "fmt"
func show(a int, b int) {
fmt.Println(a, b)
}
func main() {
show(1)
}
$ go build
# example.com/counts
./main.go:10:7: not enough arguments in call to show
have (number)
want (int, int)
The position is the argument that is missing a partner — column 7, where the lone 1 sits — and the indented lines give the argument types the call supplied against the parameter types the function declares. This is the pass-through rule's ordinary counterpart: arguments are assigned to parameters one by one, so their counts are checked the same way, but the message belongs to calls, not assignments, and no tuple language appears in it.
A return statement has its own version of the check. The pass-through return shown earlier works when the counts match; when a function tries to return a multi-valued call whose results outnumber its own result list, the message is again a have and want pair, under a different headline:
// main.go
package main
func pair() (int, int) {
return 1, 2
}
func one() int {
return pair()
}
func main() {
_ = one()
}
$ go build
# example.com/counts
./main.go:8:9: too many return values
have (int, int)
want (int)
Three count checks, three wordings. assignment mismatch means the variables in front of an assignment disagree with the values behind it. not enough arguments and too many arguments mean a call's argument list disagrees with a parameter list. too many return values and its counterpart mean a return statement disagrees with the function's result list. Reading which headline appeared is the fastest way to locate the list that was counted wrong, because each check guards a different list.
The fixes, ranked
Bind every value. The default fix for an assignment mismatch is to give the operation the number of variables it produces values for — a, b := pair() for a two-value call, two variables for a map index, assertion, or receive whose report matters. Most mismatches in working code are this case wearing a disguise: a function grew a second return value, usually an error, and a call site still receives it the old way. The fix is to receive the new value and handle it, not to blank it — a blanked error is a decision, and it should be made on purpose, with the value in hand.
Blank the values that are unwanted on purpose. When a value is genuinely not needed — the first half of a pair whose report is the point, the second half whose value is — the blank identifier takes that slot at the assignment itself: _, ok := m[k], v, _ := <-ch, a, _ := pair(). The blank must be one of the counted variables, in the position of the value it discards; there is no form that receives fewer variables and discards the rest implicitly, which is precisely what the mismatch error enforces.
Pass the values through. When the values are bound only to be handed on — returned from a wrapper, or passed to a function with matching parameters — skip the binding entirely. return pair() and show(pair()) state the forwarding directly, keep the counts in exactly one place (the two signatures), and cannot drift out of step the way an intermediate pair of variables can.
Split a mixed assignment. When the failing line combines a multi-valued call with expressions of its own, no adjustment of the variable count fixes it, because the call does not expand inside a list. Bind the call in its own assignment, then combine the resulting ordinary variables in a second statement.
Check which list was counted. When the headline is not assignment mismatch, the fix belongs to the other list: arguments for a call message, result values for a return message. Adjusting the variables in front of an assignment cannot repair either, and the have and want lines state both sides of the disagreement directly.
Which fix for which cause
| What the code shows | Cause | Fix |
|---|---|---|
Fewer variables than a call returns (1 variable but pair returns 2 values) |
The receiving side was written for a single value, or the function grew a return value the call site has not caught up with | Bind every value: add a variable for each return, and handle the new one — usually an error — rather than blanking it by reflex |
More variables than a call returns (3 variables but pair returns 2 values, 2 variables but single returns 1 value) |
The receiving side assumes a return that the function does not produce | Compare the signature with the declaration; remove the extra variable, or call the function that does return that many values |
A multi-valued call inside an expression or condition (multiple-value pair() ... in single-value context) |
The call was treated as one value; Go has no first-value convention | Bind the values in an assignment first, then use the variable the expression actually needs |
Three variables in front of a map index, type assertion, or channel receive (3 variables but 1 value) |
These operations have a one-value form and a two-value special form, and no three-value form | Use two variables for the value plus its report, or one for the value alone |
A multi-valued call beside other expressions (pair(), 3 reported as 2 values) |
A call expands to fill several variables only when it stands alone on the right side; in a list it counts as one entry | Split the assignment: bind the call on its own line, then combine the plain variables |
A call used for its effect, results unwanted (pair() as a statement, or _, _ = pair()) |
Not an error — statement calls discard their results, and the blank form discards them explicitly | Leave it, if the discard is the intent; bind the values if any of them turns out to be needed |
not enough arguments / too many arguments with have and want lines |
A call's arguments disagree with the callee's parameters — a different check from the assignment count | Fix the argument list or the signature named in the want line |
too many return values with have and want lines |
A return statement disagrees with the function's own result list | Match the return to the result list, or widen the result list if the function is meant to return the pair |
Checklist
- Before changing anything, read both counts in the message: the variables on the left, the values on the right, and the name of the function or operation that produced them. The fix is almost always visible in that one line.
- Before adding a variable, check the signature of the function named in the message. A mismatch usually means one side was edited and the other was not, and the signature says which count is intended.
- Before blanking a value, decide whether it is unwanted or unhandled. An unwanted value gets a
_in its slot; an unhandled error gets received and dealt with. - Before wrapping a multi-valued call in an expression, a conversion, or a condition, bind it first. Every single-value context rejects the call itself, whatever surrounds it.
- Before padding an assignment with an extra expression, check whether a multi-valued call is on the right side. If it is, it must stand alone; split the line.
- Before reaching for a third variable on a map index, a type assertion, or a channel receive, stop at two: value and report are all any of them offers.
- Before treating a count error as an assignment problem, read its headline.
haveandwantlines mean a call's arguments or a function's returns were counted, and the repair belongs to that list instead.
Related guides on this site
- Fix Go "Declared and Not Used" and "Imported and Not Used" Compile Errors — the other counting rule a new Go file meets first: every local variable and import must be used, and the blank identifier is its deliberate-discard mechanism as well.
- Go Slices and Maps — the map operations behind this guide's two-value index form, whose report separates an absent key from a stored zero.
- Go Structs and Interfaces — the interface values whose dynamic types the two-value type assertion form tests without panicking.
- Fix the errgroup Worker Pool Race in Go — multi-value returns under concurrency, where the error half of the pair is the one that must never be blanked by reflex.
Sources
- The Go Programming Language Specification — for tuple assignment (a tuple assignment assigns the elements of a multi-valued operation to a list of variables; in its first form the right-hand operand is a single multi-valued expression such as a function call, a channel or map operation, or a type assertion, and the left-hand count must match the number of values; in its second form the left-hand count must equal the number of right-hand expressions, each of which must be single-valued), for the call special case (if the return values of a function or method
gare equal in number and individually assignable to the parameters of another function or methodf, the callf(g())passes them in order, the call offmust contain no other parameters, and a final variadic parameter offreceives the return values that remain), for the map index special form (an index expression on a map used in an assignment of the formv, ok = a[x]yields an additional boolean reporting whether the key is present), for type assertions in the same special form (yielding the asserted value and a boolean report instead of a panic), for the receive operator (the multi-valued assignment form reports whether a received value was sent before the channel was closed), for expression statements (function and method calls may appear in statement context), and for return statements (including returning a single multi-valued expression whose results match the function's result list). - Effective Go — for the multiple return values discussion: functions and methods can return multiple values, the form that lets a call such as
Writereturn a count and an error together, and the convention of receiving and acting on both halves of such a pair.
Keep Exploring
The full Go hub \u2014 slices and maps, concurrency, and the standard library.
Every guide on the site in one list, grouped by topic.
Every browser-only checker and verifier on the site.
The C++, Python, Sysadmin, Rust, Go, and TypeScript hubs.